Frontend Project Context

Keep AI coding guidance consistent with one human-approved, source-traceable project contract.

用一份经过人工批准、来源可追溯的项目合同，让不同 AI 编程工具获得一致且不过期的项目上下文。

English · 中文

English

Why use it?

AI coding tools often read only part of a repository. Important conventions may be scattered across documentation, configuration, source code, and team decisions. Frontend Project Context turns those explicit sources into a project-local Project Contract, then:

• selects the approved guidance that applies to a file or directory;
• renders focused context for existing coding agents;
• exposes versioned machine capabilities, schemas, and human-reviewed evidence bundles for model-neutral hosts;
• converts AI suggestions into authority-free Action Plans and read-only Review Bundles;
• publishes managed Markdown, AGENTS, or Ruler-compatible projections;
• reports source, contract, and projection drift;
• keeps every persistent write and approval under explicit human control.

It does not call an AI provider, edit business code, manage Git, install dependencies automatically, or approve rules on its own.

Version 1.10.1 includes the approved context-first handoff: a project brief, a minimal task record, a read-only handoff result, and instructional context gates. Real-project Agent acceptance remains pending; this release does not claim that a Host will always follow the gates.

Requirements

• Node.js 18 or newer
• A project whose context should live in the repository

Install

Pin it as a development dependency so local users and CI run the same version:

npm install --save-dev --save-exact [email protected]

The package has zero runtime dependencies.

1.10.1 retains the 1.10.0 interfaces and adds task-save and direct task-handoff --record, including opt-in work views. Capabilities schema remains 11 and AI Entry renderer advances to 8; Context Bundle schema 1, Coverage Audit schema 2, Contract schema 3, and Exchange Protocol 9 remain readable. Install the exact version before updating an existing project's owned AI Entry.

Quick start

Every initializing Host begins by loading the package's single normative instruction and resolved target root:

npm exec --offline -- project-context instructions --project . --prompt
npm exec --offline -- project-context status --project . --json

The only initialization procedure is AI Project Initialization. The examples below document individual governance primitives; they are not a second initialization workflow and must not be composed in place of that instruction.

All npm exec --offline -- project-context commands below require the exact development dependency installed above. --offline makes a missing local binary fail closed instead of downloading the unrelated project-context package from a configured registry.

status classifies uninitialized, partial, invalid, attention, clean, and ownership-conflict states without reading business source bodies or writing project files. After initialization, publish a fixed startup route into a managed region of root AGENTS.md while preserving all human content outside that region:

npm exec --offline -- project-context publish-entry --project . --output AGENTS.md --write --json

Version 1.10.1 uses AI Entry renderer 8: it routes through work views with explicit intent and the current consumer, using task-save for computed task records and task-handoff --record for direct handoff. It delivers the same full Context alongside task evidence, confirmed decisions and progress; unknown paths still require locate-then-targeted consumption. Existing renderer-1/2/3/4/5/6/7 entries remain readable but stale until an explicit owned republish. Published 1.10.0 retains its renderer-7 interfaces; use the commands supported by the exact package installed in the target project.

Use remove-entry with the same output to remove only a trusted managed region. Plans and previews never include --write; human approval of the exact path remains required.

Let an existing Coding Agent prepare deterministic onboarding candidates:

npm exec --offline -- project-context setup \
  --project . \
  --id my-project \
  --name "My Project" \
  --write \
  --json

setup creates only the three stores and a create-only proposal. It does not approve candidates or publish Agent files. Its JSON artifacts receipt reports the exact proposal path and whether it was previewed, created, or already unchanged. Read summary, workUnits, and readTargets, then review the exact proposed IDs.

setup is idempotent for an initialized project; it does not reset stores or translate already approved statements. Before an explicitly authorized fresh reinitialization, preserve every human-authored policy, validation description, manual source, and approval decision. Remove only a trusted managed AI Entry, clean up the exact disposable Project Context files externally, rerun setup from the installed package, then re-author and reapprove the preserved rules.

Register an explicit source:

npm exec --offline -- project-context register \
  --project . \
  --id source.package \
  --kind file \
  --path package.json \
  --write

Propose a scoped contract item. This creates a reviewable proposal; it does not approve it:

npm exec --offline -- project-context propose \
  --project . \
  --id policy.ui-copy \
  --kind policy \
  --subject ui.visible-copy \
  --value required \
  --statement "Use the approved visible-copy convention." \
  --sources source.package \
  --scope path-prefix \
  --scope-path src \
  --output .project-context/policy.ui-copy.proposal.json \
  --write

Approve only the item you reviewed:

npm exec --offline -- project-context approve \
  --project . \
  --proposal .project-context/policy.ui-copy.proposal.json \
  --ids policy.ui-copy \
  --by YOUR_NAME \
  --write

Compile context for a target and check for drift:

npm exec --offline -- project-context context --project . --path src --locale en
npm exec --offline -- project-context check --project .

For task-sensitive routing, save a schema-1 Context Query with the current snapshots and run:

npm exec --offline -- project-context context-query --project . --input .project-context/context-query.json --json
npm exec --offline -- project-context context-query --project . --input .project-context/context-query.json --prompt
npm exec --offline -- project-context coverage-audit --project . --json
npm exec --offline -- project-context index-context --project . --json

context-query --json returns the auditable machine bundle. --prompt returns its digest-bound, model-facing Markdown projection without the deferred/review envelope. When the complete applicable Context is no larger than the machine review bundle, the projection deterministically falls back to the complete Context; otherwise it uses the selected evidence closure. index-context is read-only unless --write is explicit; its persisted output is disposable derived data.

After project sources or implementation paths change, create one read-only reconciliation work unit:

npm exec --offline -- project-context sync \
  --project . \
  --changed-path src/example.ts \
  --json

sync reports changed sources, affected item IDs, pending-item review, path-scoped guidance, projection-only findings, and exact work units. It contains no source bodies and cannot accept, revise, approve, deprecate, or publish anything. A Coding Agent may prepare the existing safe commands, but a human must approve the displayed IDs and paths before writes occur.

Discover the exchange contract without initializing the project:

npm exec --offline -- project-context capabilities --project . --json

An external AI host can create an Action Plan schema 2 using the returned project snapshots and one of the ten advertised action kinds. Schema-1 plans remain readable. Save that short-lived plan inside the project, then produce a read-only Review Bundle:

npm exec --offline -- project-context preflight \
  --project . \
  --plan .project-context/action-plan.json \
  --json

preflight validates the project ID, all three snapshot digests, action-specific baselines, exact impacts, blockers, and projection ownership. It returns structured { command, args } invocations without --write or --by. The plan and Review Bundle grant no authority: after a human approves exact action IDs and paths, the host must add the required identity and write flags to the existing fine-grained command. Any intervening write invalidates the remaining review and requires a fresh sync and preflight.

For multi-stage feature work, a host can provide a Task Context Plan, prior Stage Receipts, and explicit changed-path signals. Compile only the requested stage:

npm exec --offline -- project-context stage-context \
  --project . \
  --plan task-context-plan.json \
  --stage stage-render \
  --receipt stage-understand.receipt.json \
  --receipt-bundle stage-understand.bundle.json \
  --changed-path src/example.ts \
  --json

Before an external merge, compare host-provided main/branch path signals with the plan, receipts, current Contract snapshots, and checker findings:

npm exec --offline -- project-context integration-review \
  --project . \
  --plan task-context-plan.json \
  --receipt stage-understand.receipt.json \
  --receipt-bundle stage-understand.bundle.json \
  --main-changed-path src/shared.ts \
  --branch-changed-path src/example.ts \
  --json

Both commands are read-only. They do not inspect Git, read source bodies, execute the task or tests, save task state, promote decisions, or grant merge authority. Budget limits are caller-supplied canonical UTF-8 bytes and read-target counts, not model tokens.

Starting with 1.3.1, every supplied Stage Receipt must have exactly one matching --receipt-bundle. Both commands strictly validate and deterministically rebuild the complete receipt/bundle dependency chain before accepting inputBundleDigest; missing, duplicate, mismatched, tampered, stale, or blocked inputs fail closed.

To turn an already-redacted local observation into a deterministic Evidence Bundle, keep the input JSON inside the project and run:

npm exec --offline -- project-context evidence --project . --input evidence-input.json --json

evidence reads only the supplied input plus Project Context health metadata, writes nothing, and never uploads. It excludes project identity, paths, source bodies, logs, and Contract values by structure. The two summary fields remain free text, so every bundle is permanently marked human-review-required; a person decides whether and where to transfer it.

After a human and the Host pin an exact target package version outside this product, assess the project-owned migration surface and create one digest-bound work unit:

npm exec --offline -- project-context upgrade-check --project . --from-version 1.5.0 --json > .project-context/upgrade-assessment.json
npm exec --offline -- project-context upgrade-plan --project . --assessment .project-context/upgrade-assessment.json --json > .project-context/migration-plan.json
npm exec --offline -- project-context upgrade-apply --project . --plan .project-context/migration-plan.json --json
npm exec --offline -- project-context upgrade-apply --project . --plan .project-context/migration-plan.json --write --json

upgrade-check and upgrade-plan are permanently read-only. upgrade-apply previews by default and can write only the single compiled, product-owned unit shown in that exact plan. Re-run check and plan after every unit. Even coreMigration: complete still requires the Host to verify dependency/lockfile pins, project tests or CI, and an independent new window. The product does not run a package manager, Git, network, project tests, business writes, automatic approval, rollback, or publication.

The package publishes twenty machine schemas, including capabilities 9, project status, projection lock 1/2, Migration Manifest 2, Upgrade Assessment/Migration Plan/Upgrade Result Bundle 1, Evidence Input/Bundle, Assist/Action/Review bundles, the four staged-context schemas, Context Query/Adaptive Context Bundle/Routing Index 2, and Coverage Audit 2.

Generate the read-only governance dashboard:

npm exec --offline -- project-context dashboard --project . > project-context-dashboard.html

The dashboard is a self-contained offline HTML file. The command writes only to stdout and does not open a browser or change the contract.

What is created?

Initialization creates:

.project-context/
├── contract.json
├── sources.lock.json
└── projections.lock.json

Commit these three stores. Also commit any managed projection your team intentionally publishes. Proposal files, temporary context output, dashboard HTML, caches, and tarballs should normally remain uncommitted.

Core workflow

Explicit project sources
→ reviewable proposals
→ human-approved Project Contract
→ scoped Context Bundle
→ AGENTS / Markdown / Ruler projections
→ existing AI tool
→ authority-free Action Plan
→ read-only Review Bundle
→ exact human approval
→ existing fine-grained write command
→ drift check

All commands are read-only unless that command explicitly includes --write. Source changes invalidate affected approvals; they are never accepted or reapproved automatically.

Common commands

| Command | Purpose | | --- | --- | | setup | Aggregate safe initialization, conservative discovery, and an Assist Bundle | | capabilities | Discover protocol versions, schemas, action kinds, initialization, and permanent boundaries | | evidence | Build a deterministic, read-only, human-reviewed Evidence Bundle from a project-local input | | init | Create an empty project contract safely | | register | Register a file, path, JSON pointer, or human decision | | discover | Conservatively propose bootstrap candidates | | propose | Author a fact, policy, reference, or validation description | | approve | Explicitly approve selected proposal IDs | | context | Compile approved context for one or more paths | | project-brief | Read project health and discover bounded local task records without selecting one | | task-handoff | Compile current task evidence, read targets, gaps, and an instructional gate | | context-query | Compile adaptive review JSON or its compact model-facing --prompt projection with complete-context fallback | | coverage-audit | Audit declared registration coverage without claiming all project truth | | index-context | Preview or explicitly persist a disposable routing index | | publish | Write an owned AGENTS, Markdown, or Ruler projection | | check | Detect stale sources, contracts, and projections | | sync | Aggregate source drift, item impact, changed paths, and reconciliation work units | | preflight | Validate an Action Plan and return a read-only grouped Review Bundle | | stage-context | Rebuild receipt/bundle inputs and compile the explicitly requested stage within caller-provided byte/read-target budgets | | integration-review | Review paired receipts/bundles, host path signals, baselines, and context-layer conflicts without Git | | reconcile-truth | Reconcile explicit branch/promotion evidence against the current truth baseline without reading Git or CI | | dashboard | Render the read-only governance dashboard | | review-source | Review a changed source and its exact impact set | | accept-source-change | Accept a pinned source digest and revoke affected approvals | | revise / deprecate | Maintain contract items explicitly | | deprecate-source | Retire an unreferenced source with an audit record |

Run npm exec --offline -- project-context --help for the complete command syntax.

Documentation

• User and AI operation manual
• Product constitution
• Program and CLI design
• Acceptance contract
• Installation and distribution
• Knowledge maintenance
• Read-only governance dashboard
• Source lifecycle
• Guided onboarding and AI-assisted reconciliation
• AI exchange boundary
• Branch-aware staged context and handoff
• Evidence Feedback Protocol
• Real-project source-of-truth maintenance design
• A-130 quality closure and adaptive delivery repair
• Upgrade notes

中文

它解决什么问题？

AI 编程工具通常只读取仓库的一部分，而项目约定分散在文档、配置、源码和团队决定中。Frontend Project Context 把这些明确来源治理成项目内的 Project Contract，然后：

• 按文件或目录选择真正生效的已批准规则；
• 为现有 Coding Agent 生成精简且可追溯的上下文；
• 向模型无关宿主公开版本化 capability、机器 schema 与需人工复核的证据包；
• 把 AI 建议收敛为无权限 Action Plan 和只读 Review Bundle；
• 从同一合同生成受管 Markdown、AGENTS 或 Ruler 兼容投影；
• 检测来源、合同和投影是否过期；
• 所有持久写入与批准都必须由人显式触发。

它不会调用大模型、修改业务代码、管理 Git、自动安装依赖，也不会替人批准规则。

1.10.1 按上下文优先交接设计提供项目概览、任务记录自动摘要、直接记录交接、当前意图和确认决定指导，以及准确的升级预览摘要。真实需求实施验收仍待后续观察；本版本不宣称 Host 必然遵守门禁。

环境要求

• Node.js 18 或更高版本
• 希望把 AI 项目上下文随仓库共同维护的项目

安装

建议固定为开发依赖，让本地与 CI 使用同一版本：

npm install --save-dev --save-exact [email protected]

本包没有运行时第三方依赖。

1.10.1 保留 1.10.0 接口，增加 task-save 和直接 task-handoff --record 交接及显式工作视图。Capabilities schema 保持 11，AI Entry renderer 升至 8；Context Bundle schema 1、Coverage Audit schema 2、Contract schema 3 和 Exchange Protocol 9 保持可读。先安装精确版本，再显式更新现有项目受管的 AI Entry。

快速开始

执行初始化的 Host 必须先读取包内唯一规范和 resolved targetRoot：

npm exec --offline -- project-context instructions --project . --prompt
npm exec --offline -- project-context status --project . --json

唯一初始化流程见 AI Project Initialization。下文命令只解释各治理原语，不构成另一套初始化步骤，也不能替代该指令由 Host 自行拼装流程。

以下所有 npm exec --offline -- project-context 命令都要求先安装上面的精确开发依赖。--offline 会在本地 CLI 缺失时失败封闭，避免从配置的 registry 下载无关的同名 project-context 包。

status 在不读取业务源码正文、不写项目文件的前提下分类 uninitialized、partial、invalid、attention、clean 和所有权冲突。初始化后，可把固定启动路由发布到根 AGENTS.md 的受管区域，同时完整保留区域外人工内容：

npm exec --offline -- project-context publish-entry --project . --output AGENTS.md --write --json

1.10.1 使用 AI Entry renderer 8：通过 work 视图和明确的当前意图、消费者，以 task-save 自动计算任务记录摘要，以 task-handoff --record 直接交接；交付完整 Context、任务依据、已确认决定和进度。未知路径仍需 locate → 精确文件集合，实际消费与指令式门禁保持。既有 renderer 1/2/3/4/5/6/7 可读但会标记 stale，只有显式受管 republish 才升级。已发布的 1.10.0 保留 renderer 7 接口，目标项目应使用其实际安装包支持的命令。

使用相同 output 的 remove-entry 只移除可信受管区域。计划与 preview 都不含 --write，仍需人对精确路径授权。

让现有 Coding Agent 生成确定性的首次接入候选：

npm exec --offline -- project-context setup \
  --project . \
  --id my-project \
  --name "My Project" \
  --write \
  --json

setup 只创建三个 store 和一份 create-only proposal，不会批准候选或发布 Agent 文件。JSON 中的 artifacts receipt 会返回精确 proposal 路径，以及 preview、create 或 unchanged 结果。先读取 summary、workUnits 和 readTargets，再审查具体 proposal ID。

setup 对已初始化项目是幂等操作，不会重置 store，也不会翻译已经批准的 statement。明确授权全新初始化前，必须先保留所有人工 policy、validation-description、手工 source 和批准决定；只移除可信受管 AI Entry，再由外部精确清理可丢弃的 Project Context 文件，使用已安装包重新 setup，最后重新录入并批准所保留的人工规则。

登记一个明确来源：

npm exec --offline -- project-context register \
  --project . \
  --id source.package \
  --kind file \
  --path package.json \
  --write

提出一条带作用域的合同项。这里只生成待审 proposal，不会自动批准：

npm exec --offline -- project-context propose \
  --project . \
  --id policy.ui-copy \
  --kind policy \
  --subject ui.visible-copy \
  --value required \
  --statement "使用团队已经批准的界面文案约定。" \
  --sources source.package \
  --scope path-prefix \
  --scope-path src \
  --output .project-context/policy.ui-copy.proposal.json \
  --write

人工审查后，只批准明确选中的 item：

npm exec --offline -- project-context approve \
  --project . \
  --proposal .project-context/policy.ui-copy.proposal.json \
  --ids policy.ui-copy \
  --by YOUR_NAME \
  --write

为目标目录生成上下文，并检查漂移：

npm exec --offline -- project-context context --project . --path src --locale zh-CN
npm exec --offline -- project-context check --project .

需要按任务路由上下文时，把当前 snapshot 写入 schema 2 Context Query，再运行：

npm exec --offline -- project-context context-query --project . --input .project-context/context-query.json --json
npm exec --offline -- project-context context-query --project . --input .project-context/context-query.json --prompt
npm exec --offline -- project-context coverage-audit --project . --json
npm exec --offline -- project-context index-context --project . --json

context-query --json 返回可审计的机器 Bundle，--prompt 只返回与 digest 绑定的模型面向 Markdown，不把 deferred/review 包络或 source locator 发给模型。完整 Context 在 delivery soft threshold 内或不大于 adaptive 正文时优先；非 ready 交付 stdout 为空。index-context 默认只读；只有显式 --write 才保存可删除、可重建的派生索引。

项目来源或实现路径变化后，可一次生成只读的增量维护工作单元：

npm exec --offline -- project-context sync \
  --project . \
  --changed-path src/example.ts \
  --json

sync 汇总变化来源、受影响 item ID、pending item 审查、路径适用规则、仅投影 finding 和精确 work unit。它不携带来源正文，也不能接受、修订、批准、废弃或发布任何内容。Coding Agent 可以准备既有安全命令，但只有人在看到明确 ID 和路径后才能授权写入。

无需初始化项目即可查询双向交换协议：

npm exec --offline -- project-context capabilities --project . --json

外部 AI 宿主可使用返回的三个项目 snapshot 和十类 action 生成 Action Plan schema 2；schema-1 plan 仍可读取。把这份短生命周期计划保存在项目内，再生成只读 Review Bundle：

npm exec --offline -- project-context preflight \
  --project . \
  --plan .project-context/action-plan.json \
  --json

preflight 会验证 project ID、三个 snapshot digest、action 专属 baseline、精确影响集、blocker 和投影所有权，并返回不含 --write、--by 的结构化 { command, args } invocation。Action Plan 和 Review Bundle 都不授予权限；只有人批准明确 action ID 与路径后，宿主才能为既有细粒度命令补入身份和写入参数。期间任何写入都会使余下 review 失效，必须重新 sync 和 preflight。

多阶段功能开发中，宿主可以显式提供 Task Context Plan、前序 Stage Receipt 和 changed-path 信号，只编译当前指定阶段：

npm exec --offline -- project-context stage-context \
  --project . \
  --plan task-context-plan.json \
  --stage stage-render \
  --receipt stage-understand.receipt.json \
  --receipt-bundle stage-understand.bundle.json \
  --changed-path src/example.ts \
  --json

外部合并前，可把宿主提供的 main/branch 路径信号与 plan、receipt、当前 Contract snapshot 和 checker finding 一起进行只读审查：

npm exec --offline -- project-context integration-review \
  --project . \
  --plan task-context-plan.json \
  --receipt stage-understand.receipt.json \
  --receipt-bundle stage-understand.bundle.json \
  --main-changed-path src/shared.ts \
  --branch-changed-path src/example.ts \
  --json

两个命令都不会读取 Git 或源码正文、执行任务或测试、保存任务状态、晋升决定或授予合并权限。预算由调用方以规范 UTF-8 字节数和 read-target 数量显式提供，不等同于模型 token。

从 1.3.1 起，每份 Stage Receipt 都必须恰好对应一份 --receipt-bundle。两个命令会严格验证并确定性重建完整 receipt/bundle 依赖链后再接受 inputBundleDigest；缺失、重复、错配、篡改、过期或 blocked 输入都会失败封闭。

要把一次已经脱敏的本地观察收敛为确定性 Evidence Bundle，请把输入 JSON 保持在项目内并运行：

npm exec --offline -- project-context evidence --project . --input evidence-input.json --json

evidence 只读取这份输入和 Project Context 健康元数据，不写文件，也不上传；项目身份、路径、来源正文、日志和 Contract value 按结构排除。两个 summary 仍是自由文本，因此所有 bundle 永远标记为 human-review-required，由人决定是否以及向谁转交。

在人和 Host 已于产品边界外把依赖固定到精确目标版本后，可以评估产品自有迁移面，并生成一个 digest 绑定的工作单元：

npm exec --offline -- project-context upgrade-check --project . --from-version 1.5.0 --json > .project-context/upgrade-assessment.json
npm exec --offline -- project-context upgrade-plan --project . --assessment .project-context/upgrade-assessment.json --json > .project-context/migration-plan.json
npm exec --offline -- project-context upgrade-apply --project . --plan .project-context/migration-plan.json --json
npm exec --offline -- project-context upgrade-apply --project . --plan .project-context/migration-plan.json --write --json

upgrade-check 与 upgrade-plan 永久只读；upgrade-apply 默认 preview，只有显式 --write 才能执行该 plan 展示的一个已编译、产品自有单元。每个单元后必须重新 check/plan。即使 coreMigration: complete，Host 仍需核对依赖与 lockfile、运行项目测试或 CI，并用独立新窗口复核。产品不会执行包管理器、Git、网络、项目测试、业务写入、自动批准、回滚或发布。

npm 包包含版本化机器 schema，包括 capabilities 8、initialization instruction 1、project status 2、projection lock 1/2、Migration Manifest 2、Upgrade Assessment/Migration Plan/Upgrade Result Bundle 1、Evidence Input/Bundle、Assist/Action/Review Bundle、四份 staged-context schema、Context Query/Adaptive Context Bundle/Routing Index 2 与 Coverage Audit 1。

生成只读治理看板：

npm exec --offline -- project-context dashboard --project . > project-context-dashboard.html

看板是一个可离线打开的自包含 HTML。命令只输出到 stdout，不会自动打开浏览器，也不会修改合同。

会生成什么？

初始化只创建：

.project-context/
├── contract.json
├── sources.lock.json
└── projections.lock.json

这三个 store 应提交到仓库；团队明确生成的受管投影也应提交。proposal、临时上下文、看板 HTML、缓存和 tarball 通常不提交。

核心流程

项目明确提供的来源
→ 可审查 proposal
→ 人工批准的 Project Contract
→ 按作用域编译的 Context Bundle
→ AGENTS / Markdown / Ruler 投影
→ 现有 AI 工具
→ 无权限 Action Plan
→ 只读 Review Bundle
→ 人对明确 action 的批准
→ 既有细粒度写命令
→ 漂移检查

所有命令默认只读，只有当前命令显式包含 --write 才会持久写入。来源变化后，受影响的批准会失效，但工具不会自动接受变化或重新批准。

常用命令

| 命令 | 用途 | | --- | --- | | instructions | 读取包内唯一初始化指令并固定 resolved targetRoot | | setup | 聚合安全初始化、保守 discovery 和 Assist Bundle | | capabilities | 查询协议版本、schema、action kind、初始化状态和永久边界 | | evidence | 从项目内输入生成确定性、只读且需人工复核的 Evidence Bundle | | init | 安全创建空项目合同 | | register | 登记文件、路径、JSON Pointer 或人工决定 | | discover | 保守提出首次接入候选 | | propose | 创建 fact、policy、reference 或 validation-description | | approve | 显式批准选中的 proposal ID | | context | 为一个或多个路径编译已批准上下文 | | project-brief | 只读展示项目健康与可选的本地任务记录；不自动选任务 | | task-handoff | 只读编译本次任务证据、待读项和指令式门禁；--input - 可从 stdin 接收输入 | | context-query | 编译自适应审查 JSON，或生成带完整上下文回退的紧凑 --prompt 模型投影 | | coverage-audit | 审计声明范围内的来源登记覆盖，不宣称发现全部项目真源 | | index-context | 预览或显式保存可删除的派生路由索引 | | publish | 写入仍归工具所有的 AGENTS、Markdown 或 Ruler 投影 | | check | 检测来源、合同和投影漂移 | | sync | 聚合来源漂移、item 影响、变化路径和维护工作单元 | | preflight | 验证 Action Plan 并返回只读分组 Review Bundle | | stage-context | 重建 receipt/bundle 输入，并在调用方字节/read-target 预算内编译显式指定的当前阶段 | | integration-review | 不读取 Git，只读审查成对 receipt/bundle、路径信号、baseline 与上下文冲突 | | reconcile-truth | 不读取 Git/CI，将显式分支与晋升证据对当前真源基线做只读重算 | | dashboard | 生成只读治理看板 | | review-source | 查看来源变化及精确影响集 | | accept-source-change | 接受固定摘要并撤销受影响批准 | | revise / deprecate | 显式维护合同项 | | deprecate-source | 用审计记录退役已无引用的来源 |

运行 npm exec --offline -- project-context --help 查看完整命令语法。

深入文档

• 使用与 AI 协作操作手册
• 产品宪法
• 程序与 CLI 设计
• 验收合同
• 安装与分发
• 知识维护闭环
• 只读治理看板
• 来源生命周期
• 引导式接入与 AI 辅助维护
• AI 双向交换边界
• 分支感知的分阶段上下文与交接
• Evidence Feedback Protocol
• 真实项目全量应用下的真源维护设计
• A-130 质量闭环与自适应交付协议修订
• 升级说明

License / 许可证

Apache License 2.0 · Copyright 2026 Fushan

See LICENSE and NOTICE.

日常交接工作视图

日常使用示例 将项目概览、任务交接、继续和完成后的知识建议连成同一条路径。明确添加 --view work 会输出 schema 2；不加参数或 --view legacy 保持 schema 1 与原退出码。工作视图交付同一编译器的完整 Context，实际阅读与当前消费者声明仍是必要步骤；输出超过 1 MiB 时明确 withheld，不以截断内容放行。

npm exec --offline -- project-context project-brief --project . --view work --json
npm exec --offline -- project-context task-save --project . --input task-draft.json --expected-digest absent --write --json
npm exec --offline -- project-context task-handoff --project . --record .project-context-tasks/my-task.json --intent implement --consumer-run my-consumer --view work --json

以上新任务示例适用于 1.10.1：草稿为 task-context-draft，使用真实项目 ID 和 taskId；absent 仅用于创建，更新使用当前 CLI 返回的 recordDigest。阶段由当前用户请求决定。实际读取后，以同一 --record、--intent、--consumer-run 和 --input consumption.json 复查；确认决定仍有效时复用，不重复确认。旧版 task-handoff-input wrapper 的 --input 接口继续兼容，已发布的 1.10.0 按其本地指令使用旧接口。

真实收益验收包括两个业务任务和一次无历史续接，记录准备、读取、定位、返工和维护时间。安装与本地测试通过不能替代这些实际结果。