How to Run the Knowledge Graph Lint and Reconcile Product with Code Docs in TeamAI

To validate your TeamAI knowledge graph health, execute teamai codebase --lint; to cross-reference product documentation with extracted code evidence, run teamai codebase --reconcile.

The Tencent/teamai-cli repository maintains a structured knowledge graph of your codebase inside the teamwiki/ folder. Understanding how to run the knowledge graph lint and reconcile product with code docs ensures your documentation stays synchronized with actual source implementations and that the underlying graph index remains valid for AI-powered queries.

Linting the Knowledge Graph with --lint

The --lint sub-command validates the consistency and structural integrity of your knowledge graph. Implemented in src/codebase-wiki-lint.ts, the lintTeamwiki function constructs a WikiLintReport (lines 35-43) that aggregates issues across multiple validation checkpoints.

Critical Checks Performed

The linter validates the following components with assigned severity levels:

• Graph Index Presence (high): Verifies teamwiki/.indices/graph-index.json exists and contains valid JSON
• Evidence Directory (high/medium): Confirms teamwiki/evidence/code/ exists and contains at least one project
• Project Structure (low): Checks that each project under evidence/code/ contains an index.md entry point
• Navigation Files (low): Validates existence of router.md, index.md, and hot.md wiki entry points
• Source Manifest (low/medium): Ensures teamwiki/source-manifest.json exists and is recent (< 60 days)
• Graph Health Metrics (medium/high): Analyzes node/edge counts, orphan nodes, and connectivity to detect isolated sub-graphs

Running the Lint Command

Execute the basic lint to receive a human-readable report:

teamai codebase --lint

Filter output by severity for focused debugging:

# Show only critical issues

teamai codebase --lint --severity high

Generate JSON output for automated CI pipelines:

teamai codebase --lint --json

The command produces a structured summary indicating specific failures:

❯ teamai codebase --lint
✖ graph-missing   teamwiki/.indices/graph-index.json   graph-index.json 不存在，知识图谱未构建
✖ evidence-missing teamwiki/evidence/code/            evidence 目录不存在，无代码事实页
…
Summary: 2 high, 0 medium, 0 low, 0 info issues (2 total)

Reconciling Product Documentation with Code Evidence

The --reconcile workflow bridges the gap between product documentation and code evidence pages. Located in src/wiki-engine/knowledge-reconciler.ts, the reconcileKnowledge function (lines 260-300) maps product Markdown files to corresponding code evidence and creates bidirectional linkages.

How Reconciliation Works

The process executes four key steps:

1. Validate Graph Index: Aborts if graph-index.json is missing or corrupt
2. Load Product Docs: Parses Markdown headings from your docs/ folder and extracts identifiers to locate matching code pages
3. Create Bridge Edges: Generates edges labeled with the provenance type "bridge-reconcile" (defined in src/wiki-engine/core/graph-index.schema.ts) linking product sections to code evidence
4. Persist Updates: Writes the modified graph back to disk with a status summary

Executing Reconciliation

Run the reconcile command to update bridge edges:

teamai codebase --reconcile

Combine with linting to verify changes immediately:

teamai codebase --reconcile --lint

The CLI outputs detected conflicts, such as:

✖ missing-bridge   docs/feature-x.md → evidence/code/feature-x/   No matching code page found

Complete Workflow for Knowledge Graph Maintenance

A typical maintenance cycle ensures your knowledge graph remains accurate and synchronized:

# 1. Extract fresh evidence (if not already present)

teamai codebase --extract /path/to/repo

# 2. Validate current state

teamai codebase --lint --severity high

# 3. Synchronize product and code documentation

teamai codebase --reconcile

# 4. Verify reconciliation succeeded

teamai codebase --lint

For CI automation, fail the pipeline on high-severity issues:

teamai codebase --lint --json | jq 'select(.summary.high > 0)' && exit 1

Summary

• The --lint command in src/codebase-wiki-lint.ts validates graph integrity, evidence presence, and navigation structure with configurable severity filtering.
• The --reconcile command in src/wiki-engine/knowledge-reconciler.ts creates "bridge-reconcile" edges linking product docs to code evidence pages.
• Both commands operate on the teamwiki/ directory, specifically targeting .indices/graph-index.json and evidence/code/ paths.
• JSON output and severity flags support integration into automated CI/CD pipelines for continuous knowledge graph validation.

Frequently Asked Questions

What does the knowledge graph lint check in TeamAI?

The lint command verifies that teamwiki/.indices/graph-index.json exists and is valid, confirms that teamwiki/evidence/code/ contains extracted project data, checks for required navigation files (router.md, index.md, hot.md), and analyzes graph health metrics including orphan nodes and connectivity issues. Each check carries a severity level (high, medium, low) that you can filter using the --severity flag.

How do I fix missing bridge edges between product and code docs?

Execute teamai codebase --reconcile to trigger the reconcileKnowledge function, which scans your product documentation (typically under docs/), matches sections to code evidence pages in teamwiki/evidence/code/, and creates bridge edges with the "bridge-reconcile" provenance label. If the command reports missing-bridge warnings, ensure your code evidence exists for the referenced product features or adjust your documentation identifiers to match the extracted code page names.

Can I automate the lint process in CI pipelines?

Yes. Use the --json flag to output machine-readable results and pipe the output to validation tools like jq. For example: teamai codebase --lint --json | jq 'select(.summary.high > 0)' && exit 1 will fail the build if any high-severity issues exist. The JSON structure includes the issues array and summary counts generated by the WikiLintReport class in src/codebase-wiki-lint.ts.

Where is the reconciliation logic implemented in the source code?

The core reconciliation algorithm resides in src/wiki-engine/knowledge-reconciler.ts, specifically within the reconcileKnowledge function (lines 260-300). The CLI entry point that parses the --reconcile flag is located in src/codebase-cmd.ts, and the graph schema defining the "bridge-reconcile" edge type is declared in src/wiki-engine/core/graph-index.schema.ts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}