projscan

---

适用场景

当 Agent 提出以下问题时，请使用 projscan：

• 修改此功能前，我应该先阅读哪些文件？
• 交接前应该运行哪些验证命令？
• 哪些风险需要修复、审查者关注或发布签核？
• 我应该先修复哪项风险？
• Agent 是否始终遵守已批准的变更范围？

projscan 会在你的计算机上运行核心扫描。它会遵循 .gitignore，除非你选择加入扫描，否则不会将 .env 中的值纳入扫描，并通过 CLI 和包含 51 个工具的 MCP 服务提供相同的证据。语言层使用 11 个 AST 适配器，覆盖 12 种具名语言。

Your agent / engineer
  (Codex, Claude Code, Cursor, CI, your scripts)
       |   intent, diff, repo files, feedback, proof requests
       v
  +----------------------------------------------------------------+
  |  projscan   (runs locally, source stays on this machine)       |
  |  ------------------------------------------------------------  |
  |  Mission Control -> assess Cards -> simulate risk -> prove      |
  |                         |              |              |         |
  |                         |              |              +- allowed files
  |                         |              |              +- forbidden files
  |                         |              |              +- proof receipt
  |                         |              |              +- change passport
  |                         |              |              +- review gate
  |                         |              |              +- live guard
  |                         |              +- bounded extraction       |
  |                         |              +- regression test first    |
  |                         |              +- leave unchanged          |
  |                         +- evidence strength                   |
  |                         +- trust memory                        |
  |                         +- AgentLoopKit handoff                |
  |                                                                |
  |  CLI + MCP tools, no account, telemetry off by default         |
  +----------------------------------------------------------------+
       |   next safe action, exact proof commands, handoff packet
       v
Reviewer / CI / LLM provider
  (only the evidence you choose to pass along)

安装

npm install -g projscan
projscan start

无需全局安装即可运行：

npx projscan start

请先检查信任边界：

projscan privacy-check
projscan start --intent "what can projscan read?"
projscan start --intent "does projscan read .env values?"

日常工作流

在查看完整命令目录之前，请先了解以下四种工作流。

修改功能前

projscan start --intent "what files do I need to change for auth?"
projscan start --intent "what should we build next?" # Routes to a before-edit implementation workplan
projscan start --intent "is my agent allowed to change billing retry logic?"
projscan understand --view change --intent "add auth token refresh" --format json
projscan prove --intent "is my agent allowed to change billing retry logic?"
projscan preflight --mode before_edit --format json

你将获得一份带引用的变更图、优先阅读文件、可能修改的文件、受阻输入、可执行的验证契约，以及编辑前验证关卡。Agent 权限意图会转到 projscan prove，因此 start 可以向下一个 Agent 提供契约路径，而不是一份宽泛的检查清单。

成功标准：Agent 能说出应首先阅读的文件、可能修改的文件、应避免的禁改文件，以及编辑前要运行的验证命令。

已验证的变更工作流

projscan start --intent "is my agent allowed to change billing retry logic?"
projscan prove --intent "is my agent allowed to change billing retry logic?" --save-contract .projscan/proof-contract.json
# Make the bounded edit, then run the proof command.
projscan prove --run -- npm test -- tests/billing/retry.test.ts
projscan prove --changed --contract .projscan/proof-contract.json --format markdown
projscan passport --contract .projscan/proof-contract.json --format markdown
projscan proof-broker --contract .projscan/proof-contract.json --pr-comment
projscan review-gate --contract .projscan/proof-contract.json --pr-comment

命令流程为 start -> prove -> run -> changed。创建契约后、运行 prove --run 前，进行有界编辑。start 会选择契约工作流。只有存在 --save-contract 时，prove --intent 才会写入 .projscan/proof-contract.json。prove --run -- <command...> 会执行本地验证命令、记录退出代码、捕获经过脱敏的日志，并为当前已更改文件生成指纹。当 projscan 未运行命令时，仍可使用 prove --record-command 导入 CI 或外部证据。prove --changed 会根据契约和本地记录账本检查当前工作树。

你将在编辑前获得一份验证契约，并在编辑后获得一份验证收据。契约会列出允许的文件、禁改文件、有风险的契约、可能的测试、缺失的回归测试证据、验证命令、安全的变更形式、回滚方案、置信度、审查者指南，以及各风险面对应的 proofRequirements。收据会根据该契约检查实际工作树，并将已更改文件分类为允许的生产文件、预期测试、文档、生成的验证产物、配置／安全偏移、禁改文件触碰或意外的生产文件。收据会报告验证重放状态、验证充分性、风险变化、提交就绪情况，以及审查者检查清单。 同级 Baseframe harness 目录（.agentloop/、.agentflight/）归类为 harness 证据，而非范围漂移：AgentLoopKit 和 AgentFlight 会在获准的工作流中将会话状态、任务状态转换和验证报告写入这些目录，因此这些写入在回执中仅作信息展示，绝不会触发 forbiddenTouched、阻碍提交就绪状态或阻止评审关卡。自动生成的契约不再将这些目录列入 forbiddenFiles，回执会忽略旧版本保存的契约中的此类条目，Team Proof Recipe 中的 forbiddenFiles 条目也采用相同处理方式。若要禁止访问生产路径，请继续使用 forbiddenFiles 或 Team Proof Recipe 指定非 harness 位置。

依赖变更意图会保持自身范围可执行：当 prove --intent 描述依赖或工具版本变更时（例如“将 projscan 升级到 5.0.1”），生成的契约会将 package.json 和 package-lock.json 放入 allowedFiles，而非 forbiddenFiles。无关意图默认仍会禁止修改这些清单文件。契约文件仅允许位于项目根目录中的 .projscan/proof-contract.json 或 .projscan/proof-contracts/<name>.json；--save-contract 和 --contract 会拒绝其他路径。

Proof Replay 会在 .projscan/proof-ledger.jsonl 中记录命令、退出代码、耗时、变更文件指纹、已脱敏摘要、日志路径和来源。执行的 proof 日志会保存在 .projscan/proof-logs/ 下。账本匹配会规范化包运行器前缀，因此 npx projscan assess --mode fix-first --format json、pnpm exec projscan ... 和 node_modules/.bin/projscan ... 都能满足 projscan assess --mode fix-first --format json 这一要求。prove --changed 会将 proof 标记为已通过、缺失、失败、部分完成或过期。回执 JSON 包含 proofReplay，其中提供重放时间线、changedAfterProof、重放命令和本地回执指纹。如果 Agent 在 proof 运行后编辑了新文件，评审者查看差异前，回执就会指出 proof 已过期。

Proof Sufficiency 会估算本地账本是否涵盖每个变更面。proofSufficiency 会将各行标记为强、充分、较弱、缺失、过期或失败，然后列出评审者需要解决的确切问题。

Team Proof Recipe 允许仓库通过 proofRecipes 为敏感路径编码所需的 proof；配置了匹配的 recipe 时，prove --intent 会将该 recipe 的命令、评审者和禁止文件加入 Proof Contract。随后，prove --changed 和 projscan evidence-pack --pr-comment 会在 Proof Receipt 中显示缺失的 recipe proof、所需评审者和 recipe 漂移。recipe 本身不会运行 proof 命令；请使用 prove --run -- <command...> 或 prove --record-command 将证据添加到本地账本。 已保存的契约是 prove --changed 的事实来源；团队 recipe 变更时，请更新契约。

每份 prove 报告都包含 verifiedWorkflow，这是面向 Agent 和 MCP 客户端的精简 JSON 摘要。其中会列出阶段、下一步操作、下一条命令、范围状态、proof 状态、proof 充分性状态、风险变化方向、评审者决定，以及 proof 过期／缺失／失败标记。

projscan passport 会将契约和回执整合为一份交接文件。文件中会列出允许的文件、禁止的文件、变更文件、proof 重放状态、Proof Sufficiency、评审者操作和后续命令。当评审者或其他 Agent 需要通过一个 JSON 文件了解完整变更经过时，请保存此文件：

projscan passport \
  --intent "is my agent allowed to change billing retry logic?" \
  --save-contract .projscan/proof-contract.json \
  --output .projscan/passport.json

使用 projscan proof-broker 根据相同的护照证据生成 PR Passport。其中会列出所需的 proof 条目、缺失或过期的 proof 命令、Team Proof Recipe 中的所需评审者、有风险的变更文件，以及评审者应要求执行的后续命令：

projscan proof-broker --intent "<change>" --bootstrap-contract
projscan proof-broker --contract .projscan/proof-contract.json --pr-comment

只有在明确请求时，--bootstrap-contract 才会写入新的 Proof Contract。它不会执行证明命令，也不会悄然扩大范围。

使用 projscan review-gate 根据 PR Passport 生成审查决策。它会报告 ready、needs-proof、drifted 或 blocked，说明是否可以继续审查，逐项列出证明债务，在范围发生变化时指出重新签订合约的命令，并且可以在证明债务清零前阻止 CI 通过：

projscan review-gate --intent "<change>" --bootstrap-contract
projscan review-gate --contract .projscan/proof-contract.json --pr-comment
projscan review-gate --contract .projscan/proof-contract.json --ci --fail-on-needs-proof

projscan guard 会根据已保存的 Proof Contract 检查当前工作树。在 Agent 编辑文件后使用，或在工作期间运行 --watch：

projscan guard --contract .projscan/proof-contract.json
projscan guard --contract .projscan/proof-contract.json --watch

成功标准：审查者能看到范围、证明执行情况、证明时效性、充分性，以及阻碍变更风险范围审查的具体证明债务。

交接或提交前

projscan start --intent "is this safe to commit?"
projscan assess --mode fix-first --format markdown
projscan preflight --mode before_commit --format json
projscan evidence-pack --pr-comment

你将获得变更文件的风险、一个或两个按优先级排序的后续操作、人工审查关卡、负责人路由、基线趋势记录，以及供审查者使用的准确证明命令。需要查看评估背后的原始修复队列时，使用 projscan bug-hunt --format json。

成功标准：审查者无需阅读完整扫描输出，就能看到首要修复项、剩余证明要求和任何人工签核关卡。

发布候选版本审查前

projscan release-train --format json
projscan preflight --mode before_merge --format json
projscan evidence-pack --pr-comment

你将获得只读的就绪情况证据。projscan 会报告修复项和签核关卡；这些命令不会打标签、发布、部署或提升版本号。

成功标准：发布审查会在任何人打标签或发布前，将具体缺陷与人工审批关卡区分开来。

每周以证明为先的评估

projscan assess --goal "make this repo safer to ship this week"
projscan assess --mode fix-first --format markdown
projscan simulate --plan "split bugHunt.ts into ranking, evidence, and output modules"

你将获得 Proof Cards：每条建议都包含本地证据、影响、安全的变更方式、验证命令、反馈或抑制建议，以及风险变化。添加 --baseline previous-assess.json，即可将当前风险变化与之前的运行结果进行比较。assess 会整合现有的质量、bug-hunt 和 preflight 证据；它不会发布、打标签或部署。

Proof Cards 还会显示证据强度、置信度原因、排序原因、信任记录、证据缺口，以及 AgentLoopKit 交接数据包。当已接受的建议、嘈杂发现、误报或抑制项应影响未来排序时，添加 --feedback .projscan-feedback.json。

在重构或提取前，使用风险变化模拟器。它会根据本地证据预测可能改动的文件、受影响的测试、契约界面、部署步骤、证明命令，以及变更前后的风险。它会比较范围受限的提取、测试优先和保持不变这几种方案，然后指出推荐选项。它是只读的：不会编辑文件、执行计划、发布、打标签或部署。

成功标准：团队能看到一两个价值最高的修复项、它们的重要性、如何证明其有效，以及发布就绪情况是否仍需谨慎处理或审查。

Baseframe Suite 评估产物

ProjScan 发现风险。 AgentLoopKit 管控工作。 AgentFlight 证明结果。

当 Baseframe Suite 任务需要稳定的本地产物时，运行：

projscan assess \
  --intent "Implement password reset" \
  --task-id auth-password-reset-20260626-01 \
  --emit-baseframe

ProjScan 会写入 .baseframe/evidence/<task-id>/projscan-assessment.json，并 更新 .baseframe/agent-workflow.json，不会写入 AgentLoopKit 或 AgentFlight 产物。请参阅 Baseframe Suite Integration v1。

任务控制

projscan start --intent "<goal>" 可将自然语言目标转化为执行计划：

• 当前命令
• 受阻输入
• 后续命令
• 证明队列
• 完成标准
• 审查关卡

当工作可能在多个 Agent 之间交接时，保存任务：

projscan start --save-mission .projscan/mission --intent "is it safe to commit this change?"
projscan mission-proof --mission .projscan/mission --format markdown
projscan start --mission .projscan/mission

任务包包含操作手册、任务卡片、交接提示词、证明脚本、审查关卡 JSON、审查者回复和证明日志。mission-proof 汇总已通过的证明、失败的关卡、重新运行、审查者决定以及可选的手动基线数据。

终端演示

重新生成 README 媒体资源：

npm run docs:screenshots
npm run docs:demos

5.0.0 说明

5.0.0 将 Proof Broker 和 Review Gate 转变为明确且可重启的证明优先 审查循环：

• 只有在明确请求时，projscan proof-broker --intent "<change>" --bootstrap-contract 才会写入下一个范围明确的 Proof Contract，然后返回包含引导元数据和引导后后续命令的 PR Passport 输出。
• projscan review-gate --intent "<change>" --bootstrap-contract 会在审查关卡界面上执行相同操作，并在目标工作树发生偏移时明确保留停止并重新约定的路径。
• projscan review-gate --contract .projscan/proof-contract.json --pr-comment 会打印 PR 评论 Markdown，其中包含状态、是否允许审查的决定、证明债务、 重新约定指南（如有则包含引导状态）、所需审查者、后续命令和构件路径。
• projscan review-gate --contract .projscan/proof-contract.json --ci --fail-on-needs-proof 会打印精简的 CI 摘要，并在关卡状态为 ready 之前以非零状态退出。
• Proof Broker 和 Review Gate 的 JSON 现在会保持控制台输出与嵌入式 Markdown 一致；如果合约是在审查界面中生成的，还会包含 Bootstrap 部分。
• ProjScan 会将 Review Gate 构件写入 .projscan/review-gate.json 或 .projscan/review-gates/<name>.json；并拒绝路径遍历、符号链接目标 以及无关的覆盖目标。
• MCP 仍包含 projscan_review_gate 和 projscan_proof_broker， MCP 界面保持为 51 个工具，并且会返回证据而不运行证明命令。
• 软件包导出 computeReviewGate() 和 computeProofBroker()，并提供 更新后的报告类型，包括新增的引导元数据。
• 仓库本地 Agent 工作流指南现在基于 [email protected] 运行，并采用 更新后的任务、验证、交接、发布和维护者检查惯例作为运行中的发布循环。

4.17.0 版本说明

4.17.0 推出了 Agent Change Passport 和 Live Guard：

• projscan passport --intent "<task>" --save-contract .projscan/proof-contract.json 会创建 Proof Contract，检查当前工作树，并返回一份本地 Passport，其中包含边界、回执、证明回放、证明充分性、审核者操作和后续命令。
• projscan passport --contract .projscan/proof-contract.json --output .projscan/passport.json 会写入 JSON 交接产物。ProjScan 会写入 .projscan/passport.json 或 .projscan/passports/<name>.json，拒绝路径遍历，检查符号链接路径，并拒绝覆盖无关文件。
• projscan guard --contract .projscan/proof-contract.json 会报告当前差异是否始终处于已批准的边界内。--watch 会在 Agent 会话期间轮询；当 Guard 检测到偏离时，--fail-on-drift 会以非零状态码退出。
• MCP 现在包含 projscan_passport，MCP 工具数量增至 49 个。该工具会向 Agent 返回 Passport 证据，但不会在 MCP 中增加证明命令执行功能。
• Passport 可通过 --task-id <id> --emit-baseframe 附加 Baseframe 评估证据，同时 ProjScan 仅负责其评估产物和共享清单更新。

4.16.0 版本说明

4.16.0 推出了 Baseframe Suite 评估导出功能：

• projscan assess --intent "<task>" --task-id <id> --emit-baseframe 会写入 .baseframe/evidence/<task-id>/projscan-assessment.json。
• ProjScan 会使用自身状态更新 .baseframe/agent-workflow.json，同时保留 AgentLoopKit、AgentFlight 及未知清单字段。
• 此软件包导出 createBaseframeAssessment()，以及 Baseframe v1 评估和工作流清单类型。
• 产物会在本地写入，采用原子操作，并经过任务 ID 验证，同时防范路径遍历和符号链接输出路径。

4.15.0 说明

4.15.0 强化了以证明为先的变更闭环：

• projscan prove --intent "<change>" 会在编辑前创建本地证明契约。契约会列出允许修改的文件、禁止修改的文件、高风险契约、可能需要的测试、缺失的回归测试证据、证明命令、回滚方案、置信度、Trust Memory 信号、证据缺口、审查者指南，以及每个风险面的 proofRequirements。
• projscan start --intent "is my agent allowed to change billing retry logic?" 会直接路由到 projscan prove，因此针对 Agent 权限的提示词会从范围明确的契约开始，而不是宽泛的清单。
• projscan prove --run -- <command...> 会在禁用 shell 执行的情况下运行显式的本地证明命令，将脱敏日志写入 .projscan/proof-logs/，追加一条 prove-run 台账记录，并让 prove --changed 重放已执行的证明，而不是使用自我报告的证据。
• projscan prove --changed 会根据已保存的契约验证当前工作树，并为 PR、Agent 和 CI 生成证明回执。在给出可复制的审查者决策之前，它会对变更文件分类，区分允许的生产代码修改、预期测试、文档、生成的证明制品、配置／安全性偏移、禁止触碰的内容，以及意外的生产代码变更。 回执还包含 proofReplay，其中列有重放状态、时间线事件、changedAfterProof、重放命令和回执指纹。证明充分性会显示每一行 proofRequirements 是否有强、充分、弱、缺失、过期或失败的证明。
• 团队证明配方允许仓库向 .projscanrc.json 添加按路径匹配的 proofRecipes。匹配的配方会将必需命令、审查者和禁止的偏移项加入证明契约和证明回执。
• projscan prove --record-command "<command>" --exit-code <code> 会追加一条本地证明台账记录，其中包含命令、持续时间、变更文件指纹、脱敏的输出摘要，以及可选的日志路径，用于从 CI 或其他运行器导入证明。
• 每份 prove JSON 报告都包含 verifiedWorkflow，因此 Agent 无需解析 Markdown，就能读取下一步操作、下一条命令、范围状态、证明状态、proofSufficiency 状态、审查者决策，以及证明过期／缺失／失败标记。
• 已保存的 Mission Control 套件会在 mission.sh 运行现有证明队列时追加证明台账记录。该脚本仍会为用户写入证明日志和状态 JSONL。
• 如果证明契约和台账可用，projscan evidence-pack --pr-comment 会包含最新的证明回执摘要，因此 PR 评论会显示证明状态、证明重放、审查者决策、范围、过期证明、失败证明、证明充分性、配方缺口、必需审查者、证明后变更的文件、回执指纹和重放命令。
• 证明制品更难伪造：读取证明契约和证明台账时会拒绝符号链接逃逸；证明日志会对更多独立出现的令牌／密钥格式进行脱敏；生成的任务脚本会在运行前拒绝 shell 控制语法。
• 支撑证明工作流的代码库规模更小，也更易审查：Mission Control、bug-hunt、quality-scorecard、workplan、adoption、start-mode 路由和 intent 路由中的源码热点已拆分为更专注的辅助模块，并配有架构测试。
• MCP 现已包含 projscan_prove，MCP 工具总数达到 48 个。

4.14.0 说明

4.14.0 推出了已验证变更工作流和已执行证明运行器：

• projscan prove --intent "<change>" 会在编辑前创建本地证明契约。
• projscan prove --run -- <command...> 会在禁用 shell 执行的情况下运行显式的本地证明命令，并写入一条经过脱敏的证明台账记录。
• projscan prove --changed 会为 PR、Agent 和 CI 生成证明回执。
• 如果证明契约和台账可用，projscan evidence-pack --pr-comment 会包含最新的证明回执摘要。
• MCP 包含 projscan_prove，MCP 工具总数达到 48 个。

4.12.1 说明

4.12.1 是 Proof Cards V2 发布的模拟器精度补丁：

• projscan simulate --plan 不再将 s.ts 这类单字母文件名视为宽泛计划文本的匹配项。
• 模拟器的术语重叠证据现在会过滤生成的 Agent/缓存路径和较弱的规划术语，因此当计划未指定具体的仓库目标时，日志或证明产物不会被判定为可能的文件。

4.12.0 说明

4.12.0 是 Proof Cards V2 日常信任闭环版本：

• Proof Cards 现在会显示证据强度、置信度原因、证据缺口、排序原因、Trust Memory 上下文和 AgentLoopKit 交接数据包。
• projscan assess --feedback <path> 会将本地审查者反馈应用于排序和置信度。
• projscan start --intent "is this safe to commit?" 现在会通过 projscan assess --mode fix-first 启动，并将预检保留为证明。
• projscan simulate --plan "<change plan>" 会比较有界提取、优先回归测试和保持不变这几种方案，然后推荐最安全的选项。

4.11.1 说明

4.11.1 是面向证明优先版本的公开 README 媒体更新：

• 新增了专用于 projscan assess 和 projscan simulate 的 Proof Cards 截图。
• 重新生成 README 截图，使公开媒体展示 47 个工具的 MCP 功能面。
• 更新网站交接指南，使用不可变的 v4.11.1 媒体 URL。

4.11.0 说明

4.11.0 是证明优先的工程指挥中心版本：

• projscan assess 会将质量、漏洞排查和预检证据转化为 Proof Cards，并提供修复优先指导和风险变化。
• projscan simulate --plan "<change plan>" 会在编辑前预测可能涉及的文件、测试、契约、发布流程、证明命令以及编辑前后的风险。
• MCP 现在提供 47 个工具，包括 projscan_assess 和 projscan_simulate。

MCP 设置

如果 Agent 需要在编码过程中调用 projscan，请使用 MCP。

Claude Code：

claude mcp add projscan -- npx -y projscan mcp

Codex CLI：

[mcp_servers.projscan]
command = "npx"
args = ["-y", "projscan", "mcp"]

Cursor、Windsurf、Cline、Continue、Zed 和其他 MCP 客户端可以启动相同的命令：

npx -y projscan mcp

如果客户端支持 notifications/file_changed，请添加 --watch：

npx -y projscan mcp --watch

Agent 问题

Agent 问题	CLI 或 MCP 路径
哪些文件实现了身份验证？	projscan search "auth" --format json
谁导入了此文件？	projscan semantic-graph --query importers --file src/auth/jwt.ts --format json
重命名此符号会导致哪些问题？	projscan impact --symbol buildCodeGraph --format json
我应该先修复什么？	projscan bug-hunt --format json
本周有哪些风险值得修复？	projscan assess --goal "make this repo safer to ship this week"
这个重构值得做吗？	projscan simulate --plan "split bugHunt.ts into ranking, evidence, and output modules"
我的 Agent 获准进行这项更改吗？	projscan start --intent "is my agent allowed to change billing retry logic?"
更改是否始终在范围内？	projscan prove --changed --contract .projscan/proof-contract.json --format markdown
审查者可以信任这份 Agent 交接内容吗？	projscan passport --contract .projscan/proof-contract.json --format markdown
PR 中应包含哪些证明？	projscan proof-broker --contract .projscan/proof-contract.json --pr-comment
此 PR 已准备好接受审查了吗？	projscan review-gate --contract .projscan/proof-contract.json --ci --fail-on-needs-proof
Agent 是否偏离了约定？	projscan guard --contract .projscan/proof-contract.json
哪些文件风险高而覆盖率低？	projscan coverage --format json
我的 Agent 下一步应该做什么？	projscan workplan --format json
此 PR 中应包含哪些证明？	projscan evidence-pack --pr-comment
此分支已准备好合并了吗？	projscan preflight --mode before_merge --format json

命令一览

命令	适用场景
projscan start	快速了解项目、确定操作路径并使用 Mission Control
projscan understand	查看带引用的仓库地图、运行时流程、公开契约和变更准备情况
projscan preflight	编辑、提交或合并前，判断是否继续、谨慎处理或阻止
projscan assess	以证据为先的评估，包含 Proof Cards、风险变化和优先修复建议
projscan simulate	编辑前模拟拟议变更计划的风险变化
projscan prove	可执行的 Proof Contracts、Verified Workflow JSON 和 Proof Receipts
projscan passport	本地变更通行证，包含边界、回执、证明和审阅者操作
projscan proof-broker	PR Passport，包含所需证明、证明缺口、审阅者和后续命令
projscan review-gate	审阅准备情况门禁，包含证明欠账、重新约定指导和 CI 退出状态
projscan guard	根据已保存的 Proof Contract 检查当前工作树
projscan evidence-pack	审阅证据，包含风险、负责人、证明回执和后续命令
projscan bug-hunt	根据健康状况、热点、会话和预检证据生成按优先级排序的修复队列
projscan workplan	有序的 Agent 任务，包含证明和交接文本
projscan doctor	项目健康状况、工具缺口、死代码和供应链信号
projscan review	基于结构化差异、风险、周期、函数和依赖的一键 PR 审阅
projscan impact	重命名、删除或升级前，分析文件或符号的影响范围
projscan semantic-graph	导入、导出、导入方、符号定义和包导入方
projscan dataflow	感知框架的源到汇风险
projscan hotspots	按变更频率、复杂度、所有权和覆盖率风险排序
projscan coverage	测试覆盖率较低的高风险文件
projscan dependencies	依赖清单、许可证摘要和风险说明
projscan upgrade <pkg>	根据变更日志和导入方证据离线分析升级影响
projscan audit	规范化的 npm audit 结果和 SARIF
projscan coordinate	跨工作树的冲突、认领和合并风险
projscan plugin	本地分析器和报告器插件工作流
projscan privacy-check	本地扫描边界、遥测、忽略规则和可联网路径
projscan mcp	通过 stdio 运行的 MCP 服务

需要查看标志时，请运行生成的命令帮助：

projscan help
projscan <command> --help

输出格式

命令支持 console、json、markdown、sarif 和 html 格式（适用于相应命令）。

projscan analyze --format json
projscan doctor --format markdown
projscan ci --format sarif > projscan.sarif
projscan evidence-pack --pr-comment
projscan mission-proof --write reports/mission-proof.md

证据需要离开仓库时，请使用限定范围且已脱敏的报告：

projscan analyze --report-scope src/api --redact-paths --format json
projscan analyze --report-scope "src/api,packages/backend" --redact-paths --format json
projscan doctor --report-policy apiEvidence --format markdown

配置

当仓库默认配置应纳入源代码管理时，创建 .projscanrc.json：

{
  "minScore": 80,
  "failOn": "warning",
  "baseRef": "origin/main",
  "ignore": ["**/fixtures/**", "**/generated/**"],
  "scan": {
    "includeIgnored": false,
    "scanEnvValues": false,
    "offline": false
  },
  "disableRules": ["large-*"],
  "suppress": {
    "hardcoded-secret": ["src/firebase.ts"]
  },
  "severityOverrides": {
    "missing-prettier": "info"
  },
  "proofRecipes": [
    {
      "id": "billing-critical",
      "matches": ["src/billing/**"],
      "requiredCommands": ["npm test -- tests/billing/retry.test.ts"],
      "requiredReviewers": ["@platform"],
      "forbiddenFiles": ["src/auth/**"]
    }
  ],
  "reportPolicies": {
    "apiEvidence": {
      "reportScope": ["src/api", "packages/backend"],
      "redactPaths": true
    }
  }
}

使用 suppress 可在特定路径中忽略已知误报，而不必在所有地方停用该规则。若只针对一行，可在值旁添加内联指令：

const firebaseKey = 'AIza...'; // projscan-ignore-line hardcoded-secret -- Firebase web keys are public identifiers

当某个路径需要团队特定的证明时，使用 proofRecipes；配置了匹配的配方后，projscan prove 会将其证明命令、审核者和禁止文件添加到契约和收据中。它不会自行运行证明命令。 没有 requiredCommands 的配方会被跳过，重复的配方 ID 会保留第一个有效配方。

配置文档位于 docs/GUIDE.md。

CI

使用 projscan ci 为拉取请求设置门禁：

projscan ci --min-score 80
projscan ci --changed-only
projscan ci --format json
projscan ci --format sarif > projscan.sarif

ci --format json 会让 ci.issues[] 可用于生成注释：每个问题都会包含 ruleId、severity、message、location、locations 和 remediation（前提是 projscan 有这些数据）。 doctor --format json 和 ci --format json 也会包含 scoreBreakdown，用于展示基础分数、严重性权重、类别扣分、总扣分、最终分数和等级。 默认情况下，只有在存在警告或错误时，ci 才会因分数低于阈值而失败。设置 "failOn": "info" 可启用旧版严格模式；设置 "failOn": "error" 则仅阻止错误。

GitHub Actions 示例：

name: ProjScan
on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 24 }
      - uses: abhiyoheswaran1/projscan@v1
        with:
          min-score: '80'
          changed-only: 'true'

插件

本地插件让团队无需更改 projscan 核心代码，即可添加项目专属的分析器规则和自定义人工报告。

加载本地插件

projscan plugin list
projscan plugin validate .projscan-plugins/team-radar.projscan-plugin.json
projscan plugin test .projscan-plugins/team-radar.projscan-plugin.json
PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor --reporter team-radar

运行 projscan help，查看按命令生成的支持情况矩阵。

插件文档：

• 插件编写指南
• 插件画廊
• 2.0 迁移指南
• 清单架构

支持的仓库

projscan 可读取 TypeScript、JavaScript、Python、Go、Java、Ruby、Rust、PHP、C#、Kotlin、Swift 和 C++，并在可用时使用 AST 感知型适配器。它还会检测 C、Shell、CSS、HTML、SQL、Dart、Lua、Scala 和 R 的文件级信号，以及相关的项目文件。

框架信号涵盖 React、Next.js、Vue、Nuxt、Svelte、Angular、Express、Fastify、NestJS、Vite、Tailwind CSS、Prisma、Remix、SvelteKit、Astro、Hono、Koa 和常见的 monorepo 布局。

JavaScript 和 TypeScript 使用 @babel/parser。非 JS 语言使用打包的 tree-sitter WASM 语法。已发布的软件包有 7 个直接运行时依赖；可选的语义搜索使用对等依赖 @xenova/transformers。

信任模型

区域	projscan 行为
源代码	核心扫描会读取本地文件，并将结果保存在你的计算机上。
.gitignore	被忽略的文件不会纳入扫描，除非你传入 --include-ignored。
.env	默认情况下，projscan 只报告路径。传入 --scan-env-values 后，它会读取值。
网络	audit、注册表检查、选择加入的遥测，以及可选的语义模型下载可能会连接网络。
遥测	在你运行 projscan telemetry enable 或接受 init team 提示之前，遥测处于关闭状态。
插件	设置 PROJSCAN_PLUGINS_PREVIEW=1 并运行 doctor、ci、analyze 或 plugin test --execute 等执行路径后，本地插件代码才会运行。
仓库写入	写入源代码需要显式运行修复命令。缓存、已保存的任务、Proof Contracts、Proof Ledger 条目和证明日志均保存在 .projscan* 本地目录中。

审计辅助工具：

projscan privacy-check
projscan telemetry status
projscan telemetry explain
projscan doctor --offline

供应链扫描器可能会标记 git、npm audit、web-tree-sitter、可选插件和可选语义搜索使用的包字符串或 API。上述运行时路径说明了这些功能何时会运行。

安装说明

[email protected] 有七个直接运行时依赖：

• @babel/parser
• @babel/types
• chalk
• commander
• fast-glob
• ora
• web-tree-sitter

如果 npm 在全局安装过程中显示 allow-scripts 警告，请检查其中列出的包名。projscan 核心在 5.0.0 版本的运行时不需要 node-gyp 语法构建。如果 npm 报告 projscan@latest 的安装脚本，请附上警告文本提交问题；也可以运行 projscan feedback intake --text "<warning text>" --format json，将其转化为有针对性的安装信任任务。

语法包是构建时的源，并非全局安装依赖。已发布的语法资源包括 tree-sitter-python.wasm 和 tree-sitter-c_sharp.wasm。

更多文档

• 完整指南
• 前 10 分钟
• 路线图
• 采用工作流
• Swarm 协调
• 稳定性政策
• 遥测政策
• 安全政策

贡献

提交 PR 前，请阅读 CONTRIBUTING.md。贡献采用 MIT License，并须按照其中所述完成 DCO 1.1 认证。

法律信息

• 许可证：MIT
• 免责声明：DISCLAIMER.md
• 安全政策：SECURITY.md
• 隐私声明：PRIVACY.md
• 遥测政策：TELEMETRY.md
• 商标和品牌政策：TRADEMARKS.md
• 第三方声明：THIRD-PARTY-NOTICES.md

属于