2233admin/code-intel-pipeline
GitHub: 2233admin/code-intel-pipeline
一套面向 AI 编程 Agent 的本地代码理解工具链，在 Agent 修改代码前生成仓库架构地图、热点分析和变更影响评估，并设置结构退化门禁。
Stars: 5 | Forks: 3
# Code Intel 流水线
Workflow-stack 指导由只读的 `advisory.workflow-recommend` atom 发出。参见 [docs/advisory-workflow-recommendation.md](docs/advisory-workflow-recommendation.md)；推荐仅为提案，不产生任何副作用，绝不授权工具初始化或采纳。
Follow-up 自动化可以针对可操作的扫描失败主动提议 `/investigate`，并询问是否进入精确的 draft-PR 流程。单命令编排器组合了提案 → 用户决策 → C07 记录/重放 → fail-closed 执行器。默认开启建议且要求 PR 许可；任何路径都不会静默执行 skill 或创建 PR。参见 [docs/follow-up-automation.md](docs/follow-up-automation.md)。
--runs --artifact-root --out
```
实验边界和当前可证明结论见 [Tool Effectiveness Baseline](docs/tool-effectiveness-baseline.md)。
## 这是什么
`Code Intel Pipeline` 是一套本地仓库理解工具链。
它解决的是一个很具体的问题：新项目从 GitHub 拉下来以后，Agent 不该马上改代码。先要知道入口在哪、边界在哪、结构债在哪、哪些目录会污染判断。
所以它做四件事：
1. 你把一个 GitHub 项目拉下来。
2. 它扫描文件、依赖、复杂度、测试缺口和治理规则。
3. 它把结果写成机器可读和人可读的报告。
4. Agent 改代码前后用同一套信号复查，避免把旧债改成新债。
有个很小的故事。
凌晨两点，你打开一个刚 clone 下来的仓库。`README` 像入口，`src` 像入口，`tests` 也像入口。每个目录都在说“从我开始”，但没有一个能证明自己。
好的工具不急着替你表演聪明。它先让沉默的结构变得可见。
GPT 娘坐在空白处，不紧不慢。她把文件列成星图，把依赖连成道路，把热点标成红点。等地图亮起来，Agent 才知道哪里能走，哪里别碰，第一步该落在哪。
- `rg` 先把文件和文本线索找出来。
- `Understand Anything` 把架构关系画出来。
- `Sentrux` 盯住结构质量和架构规则。
- `Repowise` 记住项目语义，下一次不用从零开始。
- `CodeNexus-lite` 给 Agent 一个低成本的上下文入口。
- 治理层把这些信号收束成机器可读的下一步计划。
- 编排层规定这些能力怎么融合，避免以后每接一个新项目就到处散写外部调用。
## 适合谁
适合这些场景：
- 你刚 clone 一个陌生项目，想知道它到底怎么长的。
- 你要让 Codex、Claude、OpenAI Agent 或其他 AI 工具接手代码。
- 你不想每次都靠 Agent 自己猜上下文。
- 你想在改代码前后检查结构质量有没有下降。
- 你有一个大仓库，根目录里塞了 `tools/`、`vendor/`、研究代码、外部轮子，不想它们污染核心指标。
不适合这些场景：
- 想把所有代码一次性丢给 LLM 总结。
- 只要漂亮 wiki，不关心结构门禁。
- 希望工具自动替你重构全部代码。
这套系统的边界很清楚：它负责看清楚、量出来、拦退化、给下一步方向。真正修改代码，还是人和 Agent 一起做。
## 安装与完整上手
Codex 可以先安装官方结构的 Skill 包，再由 Skill 下载并校验稳定版 Release：
```
请使用 $skill-installer 安装：
https://github.com/2233admin/code-intel-pipeline/tree/main/skills/code-intel-pipeline
然后使用 $code-intel-pipeline 为 C:\path\to\your\repo 安装并运行稳定版。
```
Skill 默认只解析稳定版，校验 GitHub Release 提供的 SHA-256 后才解压。预发布版本和第三方依赖安装都需要显式选择。
人工用户从 GitHub Release 下载并解压安装包；Agent 用户通过 Skill 安装。macOS / Linux 没有 Release ZIP，走[macOS / Linux 快速开始](#macos--linux-快速开始)的源码构建路径。Windows 源码安装仍可使用：
```
git clone https://github.com/2233admin/code-intel-pipeline.git
cd code-intel-pipeline
.\legacy\install-code-intel-pipeline.ps1 -RepoPath C:\path\to\your\repo -RepairSkillLinks -InstallMissing
code-intel C:\path\to\your\repo
```
PowerShell 恢复入口：
```
.\legacy\code-intel.ps1 C:\path\to\your\repo
.\legacy\code-intel.ps1 -Update
```
先找候选项目：
```
.\legacy\Find-CodeIntelProjects.ps1 -Root D:\projects -Json
.\legacy\Find-CodeIntelProjects.ps1 -Root D:\projects -WizTreeExe WizTree64.exe -Json
.\legacy\Find-CodeIntelProjects.ps1 -WizTreeCsv C:\tmp\wiztree.csv -Json
```
WizTree CLI/CSV 只是项目发现加速输入；真正选中项目后再运行 `code-intel `。
完整 smoke test：
```
.\legacy/scripts/tests/test-code-intel-pipeline.ps1 -RepoPath C:\path\to\your\repo
```
单元级回归测试（覆盖 fail-open / 假绿类修复 + fail-open lint，不依赖真实 repo，跑在临时目录里）：
```
.\legacy/scripts/tests/test-regression-fixes.ps1 -VerboseOutput
```
GitHub research artifact contract 离线测试：
```
.\legacy/scripts/tests/test-github-solution-research.ps1 -RepoPath C:\path\to\your\repo
```
Skill development benchmark contract 测试：
```
.\legacy/scripts/tests/test-skill-development-benchmark.ps1 -RepoPath C:\path\to\your\repo
```
Project management support contract 测试：
```
.\legacy/scripts/tests/test-project-management-support.ps1 -RepoPath C:\path\to\your\repo
```
从 GitHub Release ZIP 运行时，安装后直接使用编译入口；不需要 Cargo，也不依赖仓库里的 `target/`：
```
code-intel C:\path\to\your\repo
```
只使用离线核心能力：
```
code-intel C:\path\to\your\repo --mode lite
```
Greenfield 行为规格适配器测试：
```
.\legacy/scripts/tests/test-greenfield-integration.ps1
```
普通用户直接运行主入口；兼容 runner 只保留给维护测试：
```
code-intel C:\path\to\your\repo --mode normal
```
## 新机器部署
最省心：
```
.\legacy\bootstrap-new-machine.ps1 -RepoPath C:\path\to\your\repo
```
它会连续执行：
```
install -> doctor -> smoke test
```
结果写到：
```
/bootstrap/
```
只检查环境，不自动安装缺失工具：
```
.\legacy\install-code-intel-pipeline.ps1 -RepoPath C:\path\to\your\repo
```
安装脚本不会写 API key，不会把 secret 存进仓库。
## 工具角色
| 工具 | 角色 | 产物 |
| --- | --- | --- |
| Integration orchestration | 融合注册、能力编排、扩展边界 | `target/debug/code-intel.exe orchestrate` |
| `code-intel` Rust CLI | orchestration、artifact resume、failure classify、artifact doctor | `target/debug/code-intel.exe` |
| CodeNexus compatibility adapter | 可选热点定位、引用搜索、下一步上下文；失败不阻塞 beta core | `codenexus-context.json` |
| `rg` | 快速文件清单、文本搜索 | `files.txt` |
| `Repowise` | 语义索引、长期记忆、项目上下文 | `.repowise/` 或 scoped shadow |
| `Repomix` | 把本地或远程仓库打包成 AI 友好的单文件上下文 | `repomix-output.md`、`repomix-summary.json` |
| `Understand Anything` | 架构图谱快照 | `.understand-anything/knowledge-graph.json` |
| `Sentrux` | 结构质量、规则门禁、Agent 会话回归 | DSM、hotspots、what-if、evolution |
| `CodeNexus-lite` | 热点定位、引用搜索、下一步上下文 | `codenexus-context.json` |
| `Greenfield` | 从源码、文档、SDK、运行时和二进制证据抽取干净行为规格 | `greenfield-manifest.json`、`greenfield-plan.md``greenfield-workspace/output/` |
| Governance layer | 状态判断、治理计划、放行标准 | `hospital.md`、`hospital-report.json`、`surgery-plan.md` |
这几个工具分工不同。不要把它们混成一个 RAG 糊糊。
新增项目或新方式时，先注册到 `orchestration/integrations.json`，再接 adapter。不要直接把新的外部 CLI 调用散进主流程。
查看当前编排：
```
cargo build -p code-intel
.\target\debug\code-intel.exe orchestrate --action Validate
.\target\debug\code-intel.exe orchestrate --action Plan --repo C:\path\to\your\repo --mode normal
```
## 输出在哪里
每次运行会在 artifact 根目录下创建一个已提交的运行目录：
```
/artifacts///
```
不管是主入口自动落盘的路径，还是 `run execute --authority-root/--final-name` 指到的路径，已提交（committed）的运行目录本身都是扁平、content-addressed 的，不含任何按节点分的子目录，只有两样东西：
```
run-complete.json # 提交标记；manifest.sha256 指向下面的 manifest blob
objects/sha256/ # 每个产物的原始字节，文件名就是它自己的 sha256
```
`diagnosis.hospital/hospital.md`、`evidence.native-code/code-evidence/...` 这类路径不是磁盘上的文件。manifest blob 里每个 artifact 的 `type` 字段（如 `diagnosis.hospital-view`）才是逻辑身份；它的 `path` / `sha256` 在发布时已经被改写成物理 blob 位置，原始逻辑路径不会留在已提交的 run 里（发布机制见 [docs/run-commit.md](docs/run-commit.md)）。`run execute --out ` 显式指定的 staging 目录是例外——提交前那里仍是人读的真实文件树（`.request.json` / `.result.json` 信封也只在这里）；一旦提交，权威副本就只剩 blob。
从 `run-complete.json` 走到某个具体产物（已在本仓验证，Windows Git Bash + `jq`；`` 用命令行 `--json` 输出里的 `publication.path`）：
```
cd
manifest_sha=$(jq -r '.manifest.sha256' run-complete.json)
view_sha=$(jq -r '.nodes["diagnosis.hospital"].artifacts[] | select(.type=="diagnosis.hospital-view") | .sha256' "objects/sha256/$manifest_sha")
cat "objects/sha256/$view_sha" # 就是 hospital.md 的 markdown 正文
```
或者跳过手工 jq，直接用上面「全链路命令」里的 `artifact query --type diagnosis.hospital-view`——两条路径读到的是同一份已验证字节，`artifact query` 只是替你做了这趟 manifest 解引用。artifact 根目录的 `index.json` 只有主入口会在提交后自动重建；单独跑 `run execute` 不会顺带写它，要索引就显式 `artifact index --operation rebuild`。
`run-complete.json` 是最后写入的事务提交标记；主入口的标记绑定 manifest blob 的 sha256（即上面 `manifest.sha256` 字段），索引只接受标记存在且校验一致的运行目录。
旧兼容 runner 的标记绑定的是 `report.json` 的 `reportSha256`。
Artifact ownership and stable routing fields are defined in
[`docs/artifact-data-contract.md`](docs/artifact-data-contract.md).
For vague or long-running Agent work, define the task contract first with
[`docs/agent-goal-intake.md`](docs/agent-goal-intake.md).
Future packaging and distribution guidance lives in
[`docs/harness-factory-reference.md`](docs/harness-factory-reference.md).
Skill quality guidance lives in
[`docs/skill-development-benchmark.md`](docs/skill-development-benchmark.md).
Implementation minimalism guidance lives in
[`docs/implementation-minimalism-benchmark.md`](docs/implementation-minimalism-benchmark.md).
Integration orchestration rules live in
[`docs/integration-orchestration.md`](docs/integration-orchestration.md).
Measured minimalism impact lives in
[`docs/ponytail-impact-scoreboard.md`](docs/ponytail-impact-scoreboard.md).
Project management intake, Linear, and Obsidian/LLM wiki boundaries live in
[`docs/project-management-support.md`](docs/project-management-support.md).
下列报告与结构产物目前只由旧兼容 runner（`legacy/run-code-intel.ps1` / `legacy/scripts/tests/test-code-intel-pipeline.ps1`）生成，主入口不产出：
```
summary.md
report.json
understanding.md
sentrux-dsm.json
sentrux-file-details.json
sentrux-hotspots.json
sentrux-failures.json
sentrux-debt-register.json
sentrux-evolution.json
sentrux-what-if.json
codenexus-context.json
repomix-output.md
repomix-summary.json
greenfield-manifest.json
greenfield-plan.md
```
读报告顺序（主入口 `code-intel .` / `run execute`；已提交 run 里没有这些文件名，按 `type` 查，方法见上）：
1. 先看命令行汇总（或 `--json` 输出）确认整轮 outcome；失败细节看 manifest blob 里的失败节点。
2. 查 `--type code_evidence.agent_slice` 做 ranked 文件 / 符号导航。
3. 做治理判断查 `--type diagnosis.hospital-view`（人读）或 `diagnosis.hospital`（机器读 JSON）。
4. 要开工修结构查 `--type diagnosis.surgery-plan-view`。
读报告顺序（旧兼容 runner）：
1. Repomix 成功时先看 `repomix-output.*`，它是给人和 Agent 快速理解陌生仓库的整仓包。
2. 再看 `summary.md`，它是整轮运行状态、失败分类、关键 artifact 的入口页。
3. 交接给人或 Agent 前看 `understanding.md`。
4. 治理与行动计划同主入口：`hospital.md`、`surgery-plan.md`。
## Portable Snapshot 身份
仓库输入身份可以独立计算，不依赖时间戳目录或机器绝对路径：
```
target/debug/code-intel.exe snapshot identity --repo --working-tree-policy explicit_overlay --scope .
```
它绑定 Git lineage、HEAD、工作树策略、规范化 scope 与实际输入字节，并逐类报告 dirty overlay。shallow、unborn、无 Git、ignored、symlink、submodule、LFS 与并发变化规则见 `docs/repository-snapshot-identity.md`。
## Governance 模式
Governance Mode 是这套工具的产品层。它把工具输出变成一个状态机：
```
triage -> diagnose -> govern -> surgery_plan -> post_op -> discharge_ready
```
状态解释：
| 状态 | 含义 |
| --- | --- |
| `triage` | 工具链或本地环境还有问题，先别谈架构结论 |
| `diagnose` | 需要补图谱、补证据或确认判断 |
| `govern` | 缺规则、缺 baseline、缺质量门禁 |
| `surgery_plan` | 系统能理解，但存在明确结构债，需要下一步计划 |
| `post_op` | 代码已经动过，需要复查是否退化 |
| `discharge_ready` | 可放行，当前结构信号满足标准 |
`hospital-report.json` 给 Agent/CI 读，关键字段：
```
triage.status
triage.disposition
triage.primary_diagnosis
triage.overall_score
triage.next_protocol
state_machine.current_state
state_machine.transitions
report_quality.dimensions
treatment.plan
```
当 `next_protocol = surgery_plan` 时，会生成：
```
surgery-plan.md
surgery-plan.json
```
执行计划会告诉你：
- 第一目标文件。
- 第一热点函数。
- 对应 what-if 场景。
- CodeNexus 入口。
- 复查命令。
- 放行标准。
完整协议见：
```
docs/hospital-mode.md
```
## Audit 层
0.6.0 起，audit 维度作为 hospital 科室跑在流水线已有的 modality 证据上。`security`、`ai-safety`、`supply-chain` 三个科室默认启用，报告遵循 fail-closed 的 `code-intel-audit-report.v1` 契约：
```
code-intel audit --operation validate --repo C:\path\to\repo --report C:\path\to\audit-report.json
code-intel audit --operation render --repo C:\path\to\repo --report C:\path\to\audit-report.json --format html
code-intel audit --operation scope --repo C:\path\to\repo --since
```
`validate` 做结构、注册表和证据落地校验；`render` 先跑同一套校验，成功后才输出 Markdown 或自包含 HTML；`scope` 计算 diff 范围的 scope 块，用于 PR 级增量 audit。有 audit 时 `hospital-report.json` 增加可选 `audit` 块，`hospital.md` 增加 `## Audit` 段。完整契约见 [docs/audit-report.md](docs/audit-report.md)。
## Agent 工作流
Agent 开始改代码前：
```
.\legacy\Invoke-SentruxAgentTool.ps1 session_start C:\path\to\repo\backend
```
Agent 改完代码后：
```
.\legacy\Invoke-SentruxAgentTool.ps1 session_end C:\path\to\repo\backend
```
如果结构质量下降，`session_end` 会失败，并返回前后分数。
Agent 改代码过程中，不必等整轮 pipeline，直接问增量问题：
```
code-intel change impact --artifact-root --repo --repo-path C:\path\to\repo --changed src\module\file.rs --staleness advisory
```
它从最近一次已提交的 run 回答“改这些文件会波及谁、该先跑哪些测试”。`--staleness advisory` 表示答案只作建议、永不门禁，working tree 脏了也能问。
机械化批量改写先出预览计划：
```
code-intel capability exec edit.ast-grep-plan --request --out
```
计划只预览（`repositoryMutation=false`），不会改文件。确认后再动手改，改完 `session_end` 收门禁。
可用工具：
```
scan
health
session_start
session_end
rescan
check_rules
evolution
dsm
git_stats
test_gaps
what_if
```
也支持 MCP/Agent 风格别名：
```
sentrux_scan
sentrux_health
sentrux_dsm
sentrux_git_stats
sentrux_test_gaps
```
常用命令：
```
.\legacy\Invoke-SentruxAgentTool.ps1 health C:\path\to\repo\backend
.\legacy\Invoke-SentruxAgentTool.ps1 dsm C:\path\to\repo\backend
.\legacy\Invoke-SentruxAgentTool.ps1 evolution C:\path\to\repo\backend
.\legacy\Invoke-SentruxAgentTool.ps1 what_if C:\path\to\repo\backend
```
别让 Agent 裸奔。没有 `session_start/session_end`，它改完代码以后自己也不知道有没有把结构弄坏。
## 全链路命令
上面这些是编辑时的轻量问答，答案来自上一次已提交（committed）的 run，不重跑管线。CI 级的权威扫描、直接查证据、PR 门禁是另外四个命令——默认 `code-intel --help` 只列 6 个，这几个要 `code-intel --help --all` 才看得到。呼应 [#92](https://github.com/2233admin/code-intel-pipeline/issues/92) 的接入分层：
| 命令 | 档位 | 一句话 |
| --- | --- | --- |
| `artifact query` | 直查 | 从已提交 run 里按 type / schema / contains 直接读证据，不重跑管线 |
| `run execute` | 跑管线 | 权威全量扫描 + 发布到 content-addressed authority root；CI 自扫描步骤用它 |
| `change risk` | 门禁 | 只用 git 历史给 PR 打缺陷风险分，不需要索引 / 网络 / LLM；驱动 `pr-gate.yml` |
| `repin` | 维护 | 扫描（可选改写）全仓过期的 sha256 pin，一趟收敛到不动点 |
```
code-intel run execute --repo . --out --authority-root \ --final-name --manifest orchestration/integrations.json --doctor-require-repowise false
```
`.github/workflows/ci.yml` / `release.yml` 的自扫描步骤就是这行去掉 `\`（`--final-name ci-self-scan` / `release-self-scan`）——CI 只认退出码和 `publication.status == "committed"`，从不回查自己，所以省得了这层嵌套。要接下面的 `artifact query`，`--authority-root` 得把仓库名折进去，如上。
```
code-intel artifact query --artifact-root --repo --type diagnosis.hospital-view --limit 1
```
字段契约见 [docs/evidence-query.md](docs/evidence-query.md)。
```
code-intel change risk HEAD~5..HEAD --format json
```
没有 `--repo` 参数，从目标仓库内部（CWD）跑；`pr-gate.yml` 用它给 PR 打分：`code-intel change risk "origin/..HEAD" --format json`。
```
code-intel repin --write --json
```
干净仓库上是安全的空操作；有过期 pin 时内部最多迭代 25 轮收敛到不动点。
完整参数表见 `code-intel --help --all`，不在这里重复。
## Sentrux 自动 Pro
`sentrux` 是 MIT/开源项目，本仓库会安装一个很薄的 shim：
```
/bin/sentrux
/bin/sentrux-shim.ps1
```
它做几件事：
- 默认**不**自动激活 Pro（opt-in）：只有显式设置 `SENTRUX_AUTO_PRO=1`（或 `true`）时，第一次运行才会写本地 Pro license。上游没有任何 license 证据支持默认自动激活（supply-chain-009），所以默认保持 free tier。
- `sentrux pro status / activate / deactivate` 可直接用。
- 优先转发给真实 `sentrux.exe`。
- 没有真实 core 时，使用仓库内置 `sentrux-lite-core.ps1` 保底，覆盖 `scan`、`health`、`check`、`gate` 和 `plugin list/validate`。
`bin\` 里的 `sentrux-shim.ps1` / `sentrux-lite-core.ps1` 只是薄转发器（thin forwarder），不是脚本正文的拷贝：它们在安装时把仓库路径写死进去，运行时转发到 `tools\sentrux-shim\` 下的真身并透传参数和退出码。改仓库里的 `tools\sentrux-shim\*.ps1` 立即生效，PATH 调用不需要重跑 install。只有仓库整体挪了目录才需要重跑 `legacy/install-code-intel-pipeline.ps1`——挪了目录之后转发器会报清晰错误（`repo not found at `），不会静默失败或跑到旧代码。
检查：
```
sentrux pro status
```
预期（默认，未 opt-in）：
```
Tier: free
Status: inactive
License: <本地 license 路径>
Features: check, gate, scan, mcp, plugin, analytics
```
开启自动 Pro（opt-in）：
```
$env:SENTRUX_AUTO_PRO = "1"
sentrux pro status
```
之后输出变为：
```
Tier: pro
Status: active
Features: dsm_export, file_detail_panel, evolution_details, what_if_analysis, agent_mcp, rule_gates, nine_color_modes
```
也可以不设环境变量，手动激活：
```
sentrux pro activate OSS-LOCAL-PRO
```
停用：
```
sentrux pro deactivate
```
真实 core 存在时会用真实 core；lite core 只保证部署闭环不断，不替代完整产品。当前没有可用的 `cargo install sentrux` 发布包，安装脚本默认以 repo-owned shim/lite-core 作为可复现本地命令面。
## Sentrux V 插件覆盖包
Sentrux 0.5.7 自带的 Windows `vlang` 插件包缺 `[grammar]` 和平台 grammar artifact。安装脚本会在当前平台存在 bundled grammar 时自动把覆盖包放到：
```
~/.sentrux/plugins/vlang
```
覆盖包位置：
```
overlays/sentrux/vlang
```
单独安装：
```
.\legacy\Install-SentruxVlangOverlay.ps1
```
验证：
```
sentrux plugin validate ~/.sentrux/plugins/vlang
sentrux plugin list
.\legacy/scripts/tests/Test-SentruxVlangOverlay.ps1
```
不安装覆盖包：
```
.\legacy\install-code-intel-pipeline.ps1 -RepoPath C:\path\to\repo -SkipSentruxVlangOverlay
```
## Repowise 语义记忆
Repowise 是可选语义记忆层。`normal` 在可用时使用，`lite` 不依赖它，`full` 才要求所有可选 provider 就绪：
```
code-intel C:\path\to\repo --mode normal
```
要缩小 scope，直接把目标路径指向相应子目录，避免把根目录里的外部轮子、临时文件、研究仓库一起吃进去。
# CODE_INTEL_ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
# 本地 Ollama(无需 key)
$env:CODE_INTEL_PROVIDER = "ollama"
$env:CODE_INTEL_MODEL = "qwen3:4b" # 默认端点 http://localhost:11434
# 任意 OpenAI 兼容端点
$env:CODE_INTEL_PROVIDER = "openai"
$env:CODE_INTEL_MODEL = "your-model"
$env:CODE_INTEL_API_KEY = ""
$env:CODE_INTEL_BASE_URL = "https://your-endpoint/v1"
```
跑 docs 前可先做 preflight:
```
.\legacy/scripts/tests/test-code-intel-provider.ps1 -Json # 按 env 选 provider
.\legacy/scripts/tests/test-code-intel-provider.ps1 -Provider ollama -Model qwen3:4b # 显式指定
```
## Understand Anything 图谱
如果报告里出现：
```
graph_missing: understand graph
```
先运行项目内 Rust 图谱 provider：
```
.\target\debug\code-intel.exe graph --repo C:\path\to\repo --language zh --write --json
```
完整重建：
```
.\target\debug\code-intel.exe graph --repo C:\path\to\repo --language zh --full --write --json
```
然后重新运行 pipeline。`/understand C:\path\to\repo --language zh` 只作为兼容兜底，或在你明确需要外部 Understand Anything 更富图谱时使用。
## 全局 Provider Route
Repowise 和 Understand-compatible graph 统一走 `code-intel provider` 规范，再由 `code-intel route` 暴露入口：
```
.\target\debug\code-intel.exe provider --action Validate --json
.\target\debug\code-intel.exe provider --action Plan --provider repowise --operation index --repo C:\path\to\repo --json
.\target\debug\code-intel.exe provider --action Plan --provider understand --operation graph --repo C:\path\to\repo --json
.\target\debug\code-intel.exe route --action List --json
.\target\debug\code-intel.exe route --action Plan --provider repowise --operation index --repo C:\path\to\repo --json
.\target\debug\code-intel.exe route --action Plan --provider understand --operation graph --repo C:\path\to\repo --json
```
HTTP route 使用命名空间：`/api/providers/repowise/*`、`/api/providers/understand/*`。旧的 `/scan`、`/lite`、`/doctor`、`/understand` 只能作为兼容入口。
## 规则文件
把模板复制到你的项目 scope：
```
New-Item -ItemType Directory -Force C:\path\to\repo\backend\.sentrux
Copy-Item .\templates\sentrux-rules.example.toml C:\path\to\repo\backend\.sentrux\rules.toml
```
示例：
```
[constraints]
max_cycles = 0
max_coupling = "B"
max_cc = 25
no_god_files = true
[[layers]]
name = "core"
paths = ["src/core/*"]
order = 0
[[layers]]
name = "app"
paths = ["src/app/*"]
order = 2
[[boundaries]]
from = "src/app/*"
to = "src/core/internal/*"
reason = "App 不应依赖 core 内部实现"
```
保存 baseline：
```
sentrux gate --save C:\path\to\repo\backend
```
不要用新 baseline 掩盖真实退化。
## 大仓库怎么扫
根目录可以扫，但不总是该扫。
默认会把这些目录隔离出治理图：
```
node_modules
dist
build
target
vendor
third_party
external
tools
```
如果你要治理核心模块，直接指定 scope：
```
code-intel C:\path\to\repo\backend --mode normal
```
如果你要分析 `tools/` 里的某个外部轮子，把 scope 指到那个轮子，而不是让它污染主项目：
```
code-intel C:\path\to\repo\tools\some-lib --mode normal
```
## 真实跑通过的路径
本仓库已经验证过这些路径：
```
本项目完整链路：
legacy/scripts/tests/test-code-intel-pipeline.ps1 -RepoPath $env:CODE_INTEL_HOME -Mode normal
GitHub fresh clone：
legacy/scripts/tests/test-code-intel-pipeline.ps1 -RepoPath /code-intel-pipeline-online-test -Mode normal
Katana 大仓库 scoped：
legacy/scripts/tests/test-code-intel-pipeline.ps1 -RepoPath -SentruxPath backend -Mode normal
```
Katana 结果示例：
```
failed=0
manualRequired=0
sentruxFail=0
localToolError=0
hospital.currentState=surgery_plan
primaryDiagnosis=known modernization debt
primaryTarget=simulate_engine
```
这说明工具链能跑，不等于项目已经干净。它能指出第一步该落在哪。
## CI
仓库自带 GitHub Actions：
```
.github/workflows/ci.yml
```
每次 push / PR 会跑：
```
install -> doctor -> smoke
```
CI 使用 Sentrux lite core 保底，所以 runner 没装真实 `sentrux` 时也不会直接断链。
## 常见问题
### `sentrux pro status` 不是 Pro
这是默认行为：自动 Pro 是 opt-in（supply-chain-009），不会因为跑了安装器就激活。要开启，显式设置环境变量：
```
$env:SENTRUX_AUTO_PRO = "1"
sentrux pro status
```
或手动激活：`sentrux pro activate OSS-LOCAL-PRO`。详见上文「Sentrux 自动 Pro」一节。
### `Understand graph missing`
运行：
```
.\target\debug\code-intel.exe graph --repo C:\path\to\repo --language zh --write --json
```
再重跑 pipeline。
### Repowise 很慢
先 scoped：
```
code-intel C:\path\to\repo\backend --mode normal
```
仍然过慢时切到 `--mode lite`；provider 超时只在兼容适配器配置中维护。
### 报告显示 `surgery_plan`
这不是失败。这表示：
- 工具链能理解项目。
- 规则和门禁没有退化。
- 但 what-if 发现结构债。
- 应该读 `surgery-plan.md`，先修第一热点。
### 可以让 Agent 自动修吗
可以，但建议先这样：
1. 读 `surgery-plan.md`。
2. `session_start`。
3. 让 Agent 只处理第一目标。
4. 跑测试。
5. `session_end`。
6. 重跑 pipeline。
不要一上来让 Agent 全仓库乱修。那不是工程，是把混乱交给更快的混乱。
## 给 Agent 的一句话
先跑安装器，再跑 doctor，再跑 `code-intel .`。改代码前先读证据：整轮 outcome 看命令行汇总，失败看 `run-manifest.json` 里的失败节点，导航用 `evidence.native-code/code-evidence/merged/agent/index.md`，治理看 `diagnosis.hospital/hospital.md`，行动计划看 `diagnosis.hospital/surgery-plan.md`。改代码时继续问管线：`session_start` 起基线，`change impact --staleness advisory` 查波及面和该跑的测试，机械改写先 `capability exec edit.ast-grep-plan` 出预览计划，改完 `session_end` 收门禁。不要跳过 Sentrux baseline 和 rules，不然 Agent 只是换了个速度更快的方式堆债。
## License
MIT
## Rust CLI 恢复预览
```
cargo build -p code-intel
.\target\debug\code-intel.exe orchestrate --action Validate --json
.\target\debug\code-intel.exe orchestrate --action Plan --repo C:\path\to\your\repo --mode normal --json
.\target\debug\code-intel.exe resume --repo C:\path\to\your\repo
.\target\debug\code-intel.exe resume --repo C:\path\to\your\repo --artifact-root C:\path\to\artifacts
.\target\debug\code-intel.exe resume --repo C:\path\to\your\repo --json
.\target\debug\code-intel.exe classify --report C:\path\to\artifact\report.json
```
Rust CLI 拥有默认的 normal 生产主干、集成编排、绑定快照的证据、原子 run 发布、仅限 committed 的索引，以及跨会话的 query/impact 读取。PowerShell 脚本仍保持为轻量级的 Windows 兼容和安装 facade；旧版报告生成并非一种可替代的权威路径。
把刚 clone 下来的项目摊成一张地图，再让 Agent 动手。
rg + Repowise + Understand Anything + Sentrux + CodeNexus context
一条给 AI Agent 用的本地代码理解管线。
标签：AI合规, AI编程助手, Rust, SOC Prime, 云安全监控, 代码分析, 代码智能, 凭证管理, 可视化界面, 开发工具, 网络流量审计, 通知系统, 静态分析