@c4a/context-cli 0.6.7 → 0.6.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. package/README.md +156 -220
  2. package/README.zh-CN.md +120 -160
  3. package/cli.js +1533 -869
  4. package/docs/quickstart.md +57 -70
  5. package/docs/quickstart.zh-CN.md +79 -0
  6. package/package.json +4 -4
  7. package/plugins/.agents/plugins/marketplace.json +1 -1
  8. package/plugins/.claude-plugin/marketplace.json +2 -2
  9. package/plugins/.cursor-plugin/marketplace.json +2 -2
  10. package/plugins/README.md +79 -66
  11. package/plugins/README_CN.md +62 -57
  12. package/plugins/VERSION +1 -1
  13. package/plugins/claude/.claude-plugin/plugin.json +3 -3
  14. package/plugins/claude/commands/context.md +121 -0
  15. package/plugins/codex/.codex-plugin/plugin.json +4 -4
  16. package/plugins/codex/skills/context/SKILL.md +133 -0
  17. package/plugins/cursor/.cursor-plugin/plugin.json +3 -3
  18. package/plugins/cursor/README.md +2 -2
  19. package/plugins/cursor/commands/c4a-context.md +125 -0
  20. package/plugins/skills/c4a-context/SKILL.md +133 -0
  21. package/providers/context/actions/flush-runtime-events.yaml +5 -0
  22. package/providers/context/codes.yaml +1 -0
  23. package/providers/context/graphs/workspace.yaml +53 -2
  24. package/providers/context/manifest.json +48 -12
  25. package/providers/context/provider.yaml +2 -2
  26. package/providers/context/resources/dialogue/workflow-mode-after-capture.md +22 -0
  27. package/providers/context/resources/dialogue/workflow-mode-after-creation.md +25 -0
  28. package/providers/context/resources/manuals/guides/package-outputs.md +1 -1
  29. package/providers/context/resources/manuals/reference/package-templates.md +13 -1
  30. package/providers/context/resources/procedures/package-output.md +16 -2
  31. package/providers/context/resources/procedures/runtime-event-delivery.md +86 -0
  32. package/plugins/claude/commands/continue.md +0 -85
  33. package/plugins/claude/commands/init.md +0 -36
  34. package/plugins/codex/skills/continue/SKILL.md +0 -97
  35. package/plugins/codex/skills/init/SKILL.md +0 -48
  36. package/plugins/cursor/commands/context-continue.md +0 -89
  37. package/plugins/cursor/commands/context-init.md +0 -40
  38. package/plugins/skills/context-continue/SKILL.md +0 -97
  39. package/plugins/skills/context-init/SKILL.md +0 -48
@@ -1,103 +1,90 @@
1
- # CLI Quickstart
1
+ # Start Context through an Agent
2
2
 
3
- This file is shipped with the installed CLI at `dist/docs/quickstart.md`.
4
- It is for users who have installed the `context` executable and need the next
5
- step before an agent plugin or project workspace is ready.
3
+ [简体中文](./quickstart.zh-CN.md)
6
4
 
7
- ## 1. Install Agent Plugin Entry Points
5
+ This file ships with the installed runtime. Context is designed to be used from
6
+ its Agent entry: the user states a knowledge goal, and the Agent follows the
7
+ current workflow Route. The low-level CLI exists to execute that workflow; it
8
+ is not the first interface users need to learn.
8
9
 
9
- Install the bundled agent plugin first:
10
+ ## 1. Install the Agent integration
10
11
 
11
12
  ```bash
13
+ npm install -g @c4a/context-cli@latest
12
14
  context plugin install
13
15
  ```
14
16
 
15
- The plugin adds the user-facing agent entries for workspace initialization and
16
- continuation. Exact command names depend on the host agent, but the intended
17
- flow is:
17
+ Restart or refresh the Agent host so it discovers the installed entry.
18
18
 
19
- - initialize a Context workspace through the plugin entry when available;
20
- - continue work through the plugin entry after a workspace exists;
21
- - let the agent follow `context status`, CLI diagnostics, and human gates.
19
+ ## 2. Invoke the single entry
22
20
 
23
- If the host agent has not loaded the plugin yet, restart or refresh that agent
24
- after installation.
21
+ Use `/c4a:context` for both new and existing workspaces. Describe the source
22
+ material, intended audience, and desired output in normal language:
25
23
 
26
- ## 2. Create a Project Workspace
27
-
28
- Create a standalone workspace:
29
-
30
- ```bash
31
- context init context
24
+ ```text
25
+ /c4a:context Build a traceable Agent knowledge package from the Markdown in
26
+ docs/ and the exported APIs in packages/example. Ask me before approving the
27
+ knowledge structure.
32
28
  ```
33
29
 
34
- Choose the generated workspace and starter-template language explicitly when
35
- needed; the CLI does not infer it from terminal locale or conversation text:
30
+ The entry first runs the read-only `context entry --format json` resolver. It
31
+ will either:
36
32
 
37
- ```bash
38
- context init context --language zh-CN
39
- ```
33
+ - propose initialization at a concrete project path;
34
+ - relocate into an existing Context workspace; or
35
+ - return the current `workflow.current` Route.
40
36
 
41
- Then enter it and install dependencies:
37
+ Initialization writes a new workspace and therefore remains explicit. Entering
38
+ or evaluating an existing workspace is read-only and does not need a second
39
+ confirmation.
42
40
 
43
- ```bash
44
- cd context
45
- bun install
46
- ```
47
-
48
- After initialization, read the workspace guidance:
41
+ ## 3. Follow the conversation
49
42
 
50
- ```text
51
- AGENTS.md
52
- ```
43
+ The Agent will guide the knowledge production round through source permission,
44
+ capture or code extraction, structure design, candidate compilation, review,
45
+ close, verification, and package output. At each step it should explain:
53
46
 
54
- `AGENTS.md` explains the current project, SDK references, installed Agent
55
- entry, and safe workflow contract. It is the project-local starting point after
56
- `context init`.
47
+ - what has already been established from workspace facts;
48
+ - what decision is needed now and what that decision changes;
49
+ - which evidence or report supports the decision;
50
+ - what will happen after confirmation.
57
51
 
58
- ## 3. Work Through an Agent
52
+ The Agent reads Route-selected resources and executes exact Route-selected
53
+ commands. Users should not need to translate placeholders such as `<phase-id>`
54
+ or `<collection>` into internal CLI arguments.
59
55
 
60
- Inside the workspace, ask the installed agent plugin to continue the workflow.
61
- The agent should:
56
+ ## 4. Choose a conversation mode
62
57
 
63
- 1. read `AGENTS.md`;
64
- 2. run `context status --format json`;
65
- 3. treat `workflow.current` as the current-step authority, read each
66
- `resources.required` item, and execute only the returned command or
67
- configuration action;
68
- 4. at a Gate, load an `inspection_action` Skill or Schema only for
69
- pre-decision inspection and a `resolution_action` Skill or Schema only
70
- after confirmation;
71
- 5. stop at human gates such as source scope, structure confirmation, review,
72
- and package decisions.
58
+ Ordinary mode is the default. It exposes review decisions and HTML inspection
59
+ reports so the user can adjust intermediate content.
73
60
 
74
- The CLI performs mechanical work such as source registration, capture,
75
- validation, review application, verify, close, and build. The agent performs
76
- semantic judgment only when the workflow asks for it.
61
+ Fully managed mode must be explicitly authorized in the current conversation.
62
+ It lets the Agent collapse deterministic work and delegated review surfaces,
63
+ while preserving permissions, evidence checks, validation, and verification.
64
+ The Agent still stops whenever it needs semantic reading, project
65
+ configuration, external authority, or diagnostic repair.
77
66
 
78
- When the user explicitly requests fully managed operation, the Agent starts with
79
- `context run --managed --until blocked-or-complete --format json` to collapse
80
- consecutive deterministic routes. The CLI re-evaluates every revision and
81
- stops before semantic reads, configuration, missing authority, diagnostics, or
82
- multiple commands.
67
+ ## 5. Understand the workspace
83
68
 
84
- ## 4. Manual Orientation
69
+ After initialization, the project-local `AGENTS.md` is the entry contract for
70
+ the Agent. `src/index.ts` declares the project; `sources/` keeps captured
71
+ evidence; `knowledge/` keeps approved knowledge; `dist/` contains reproducible
72
+ outputs; `.tmp/context-runtime/` contains disposable runtime state.
85
73
 
86
- When operating without an agent plugin, start with:
74
+ Do not edit CLI-owned lifecycle files to force progress. If work is blocked,
75
+ the current Route or diagnostic provides the canonical recovery action.
87
76
 
88
- ```bash
89
- context status
90
- ```
77
+ ## Maintainer orientation
91
78
 
92
- If the command reports that no workspace exists, run `context init` first. If a
93
- workspace exists, prefer the next action reported by `context status` instead of
94
- guessing lower-level phase commands.
79
+ If an Agent integration is unavailable, `context status --format json` exposes
80
+ the same current Route for manual inspection. Use `context <command> --help`
81
+ for exact flags, and prefer commands returned by `workflow.current` over
82
+ examples copied from documentation.
95
83
 
96
- Project-local SDK documentation is installed under:
84
+ The SDK reference installed in a workspace starts at:
97
85
 
98
86
  ```text
99
87
  node_modules/@c4a/context/docs/README.md
100
88
  ```
101
89
 
102
- Use those SDK docs when editing `src/index.ts` or package templates. For normal
103
- workflow operation, prefer the agent plugin and the workspace `AGENTS.md`.
90
+ Use it when a Route asks for project configuration or package-template work.
@@ -0,0 +1,79 @@
1
+ # 通过 Agent 开始使用 Context
2
+
3
+ [English](./quickstart.md)
4
+
5
+ 本文件随安装后的运行时一起发布。Context 的设计入口是 Agent:用户说明知识目标,
6
+ Agent 跟随当前工作流 Route。底层 CLI 用于执行这套工作流,不是普通用户首先需要
7
+ 学习的界面。
8
+
9
+ ## 1. 安装 Agent 接入
10
+
11
+ ```bash
12
+ npm install -g @c4a/context-cli@latest
13
+ context plugin install
14
+ ```
15
+
16
+ 重启或刷新 Agent 宿主,使其发现新安装的入口。
17
+
18
+ ## 2. 调用唯一入口
19
+
20
+ 无论创建新工作区还是继续已有工作区,都使用 `/c4a:context`。直接用自然语言说明
21
+ 来源资料、目标读者和期望产物:
22
+
23
+ ```text
24
+ /c4a:context 请把 docs/ 下的 Markdown 和 packages/example 的导出 API 整理成
25
+ 可追溯的 Agent 知识包,知识结构批准前先让我确认。
26
+ ```
27
+
28
+ 入口首先运行只读的 `context entry --format json` 解析器,并返回以下一种结果:
29
+
30
+ - 提议在明确的项目路径初始化;
31
+ - 进入已经存在的 Context 工作区;
32
+ - 返回当前 `workflow.current` Route。
33
+
34
+ 初始化会写入新工作区,因此必须保持显式。进入或求值已有工作区是只读动作,不需要
35
+ 第二次确认。
36
+
37
+ ## 3. 跟随对话完成知识生产
38
+
39
+ Agent 会引导本轮流程完成来源权限、采集或代码提取、结构设计、候选编译、审核、
40
+ close、验证和知识包产出。每个步骤都应该说明:
41
+
42
+ - 工作区事实已经确认了什么;
43
+ - 现在需要做什么决定,以及该决定影响什么;
44
+ - 哪些证据或报告支持这个决定;
45
+ - 确认后会发生什么。
46
+
47
+ Agent 读取 Route 选择的资源,并执行 Route 返回的精确命令。用户不需要把
48
+ `<phase-id>`、`<collection>` 等占位符翻译成内部 CLI 参数。
49
+
50
+ ## 4. 选择对话模式
51
+
52
+ 普通模式是默认模式,会展示审核决定和 HTML 检查报告,方便用户调整中间内容。
53
+
54
+ 全托管模式必须由用户在当前对话中明确授权。它允许 Agent 合并确定性工作并跳过
55
+ 可 delegated 的审核界面,但仍保留权限、证据检查、校验和验证。遇到语义阅读、
56
+ 项目配置、外部权限或诊断修复时,Agent 仍会停止。
57
+
58
+ ## 5. 理解工作区
59
+
60
+ 初始化后,项目内 `AGENTS.md` 是 Agent 的入口契约。`src/index.ts` 声明项目,
61
+ `sources/` 保存采集证据,`knowledge/` 保存正式知识,`dist/` 保存可重复构建的
62
+ 产物,`.tmp/context-runtime/` 保存可丢弃运行状态。
63
+
64
+ 不要通过编辑 CLI-owned 生命周期文件强行推进流程。遇到阻塞时,当前 Route 或诊断
65
+ 会给出权威恢复动作。
66
+
67
+ ## 维护者参考
68
+
69
+ 如果 Agent 接入不可用,可以用 `context status --format json` 手工查看同一条当前
70
+ Route。精确参数以 `context <command> --help` 为准,并优先执行
71
+ `workflow.current` 返回的命令,而不是复制文档示例。
72
+
73
+ 工作区安装后的 SDK 参考入口是:
74
+
75
+ ```text
76
+ node_modules/@c4a/context/docs/README.md
77
+ ```
78
+
79
+ 当 Route 要求配置项目或修改知识包模板时再读取对应手册。
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@c4a/context-cli",
3
- "version": "0.6.7",
3
+ "version": "0.6.9",
4
4
  "type": "module",
5
- "description": "Local CLI for capturing, compiling, and governing knowledge workspaces",
5
+ "description": "Local runtime and Agent integration for traceable knowledge production",
6
6
  "license": "MIT",
7
7
  "repository": {
8
8
  "type": "git",
@@ -23,8 +23,8 @@
23
23
  "context": "cli.js"
24
24
  },
25
25
  "dependencies": {
26
- "@c4a/agent-graph": "0.2.5",
27
- "@c4a/context": "0.6.7",
26
+ "@c4a/agent-graph": "0.2.6",
27
+ "@c4a/context": "0.6.9",
28
28
  "commander": "^11.0.0",
29
29
  "fast-xml-parser": "^5.10.1",
30
30
  "handlebars": "^4.7.8",
@@ -5,7 +5,7 @@
5
5
  },
6
6
  "plugins": [
7
7
  {
8
- "name": "context",
8
+ "name": "c4a",
9
9
  "source": {
10
10
  "source": "local",
11
11
  "path": "./codex"
@@ -5,9 +5,9 @@
5
5
  },
6
6
  "plugins": [
7
7
  {
8
- "name": "context",
8
+ "name": "c4a",
9
9
  "source": "./claude",
10
- "description": "Local knowledge workspace. Initialize a project and use next-step guidance to maintain it."
10
+ "description": "Start or continue a local knowledge workspace through one graph-routed entry."
11
11
  }
12
12
  ]
13
13
  }
@@ -9,9 +9,9 @@
9
9
  },
10
10
  "plugins": [
11
11
  {
12
- "name": "context",
12
+ "name": "c4a",
13
13
  "source": "./cursor",
14
- "description": "Maintain a project-local knowledge workspace through init and continue-step guidance."
14
+ "description": "Start or continue a project-local knowledge workspace through one graph-routed entry."
15
15
  }
16
16
  ]
17
17
  }
package/plugins/README.md CHANGED
@@ -1,100 +1,113 @@
1
- # Context Plugin
1
+ # Context Agent Integration
2
2
 
3
- > [中文版本](./README_CN.md)
3
+ [简体中文](./README_CN.md)
4
4
 
5
- <p align="center"><img src="./assets/logo.svg" alt="C4A Context" width="180"/></p>
5
+ <p align="center"><img src="./assets/logo.svg" alt="Context" width="180"/></p>
6
6
 
7
- Context provides a thin Agent entry for project-local knowledge workspaces. The
8
- plugin does not embed the whole workflow in one prompt. It starts from current
9
- workspace facts, then Context CLI selects the legal route, commands, gates, and
10
- Markdown/schema resources for that step.
7
+ This plugin is the conversational entry to the Context knowledge production
8
+ workflow. It lets users describe a knowledge goal to an Agent, then connects
9
+ that conversation to the local Context runtime, current workspace facts, and
10
+ Route-selected procedures.
11
+
12
+ The plugin deliberately exposes one thin public entry instead of separate
13
+ commands for initialization, source capture, review, and build. The detailed
14
+ workflow stays in the runtime's Provider bundle, where it can be selected by
15
+ current facts, validated, tested, and updated without turning the entry into a
16
+ large prompt.
17
+
18
+ ## User experience
19
+
20
+ After the integration is installed and the Agent host is refreshed, invoke the
21
+ Context entry and describe the desired knowledge:
22
+
23
+ ```text
24
+ /c4a:context Build a searchable Agent knowledge package from our architecture
25
+ documents and this repository. Preserve source evidence and show me the final
26
+ structure before approval.
27
+ ```
28
+
29
+ The same entry can initialize a requested workspace, locate an existing one,
30
+ or continue its current production round. The Agent explains user decisions in
31
+ the conversation and uses the runtime for mechanical state transitions. Users
32
+ do not need to select low-level lifecycle commands themselves.
11
33
 
12
34
  ## Install
13
35
 
36
+ The plugin is bundled with the Context runtime:
37
+
14
38
  ```bash
15
- npm i -g @c4a/context-cli
39
+ npm install -g @c4a/context-cli@latest
16
40
  context plugin install
17
41
  ```
18
42
 
19
- For a source checkout, build the CLI and plugin first:
43
+ For a source checkout, build first and install the development projection:
20
44
 
21
45
  ```bash
22
46
  bun run --filter @c4a/context-cli build
23
47
  context plugin install --dev
24
48
  ```
25
49
 
26
- Use `context plugin install --dry-run` to inspect installation and
27
- `context plugin path` to locate the bundled marketplace.
50
+ Use `context plugin install --dry-run` to inspect the host projections and
51
+ `context plugin status` to diagnose an installation. Refresh the Agent host
52
+ after changing or reinstalling the plugin.
28
53
 
29
- ## Agent entry
54
+ ## Entry contract
30
55
 
31
- The public host surface stays small:
56
+ The maintained source is [`commands/context.md`](./commands/context.md). Its
57
+ bootstrap flow is:
32
58
 
33
- - `init` creates a Context workspace;
34
- - `continue` observes and advances an existing workspace.
59
+ 1. run the read-only `context entry --language <language> --format json`;
60
+ 2. execute only its returned `next_action.command`;
61
+ 3. after workspace setup, treat `workflow.current` as the current-step
62
+ authority;
63
+ 4. read every required Route resource completely;
64
+ 5. execute only the selected action or configuration change;
65
+ 6. evaluate the workspace again.
35
66
 
36
- Continuation starts with:
67
+ The entry does not infer workspace state from surrounding files. Initialization
68
+ is executed only when explicitly requested or confirmed; entering and
69
+ evaluating an existing workspace is read-only. There is no `context continue`
70
+ primitive and no stage-specific public Skill.
37
71
 
38
- ```bash
39
- context status --format json
40
- ```
72
+ ## Progressive workflow context
41
73
 
42
- `workflow.current` is the current-step authority. The Agent reads every required
43
- resource marked `read_state: read-required`, executes only returned commands,
44
- preserves revision and authority flags, and reevaluates status after each
45
- action. Current-conversation read receipts may be passed back through
46
- `context status --resource-receipts @<file>` so unchanged resources are marked
47
- `current`. A dynamic materialization becomes a receipt only after the Agent
48
- reads the complete returned file. `context.source-body/*` resources are source
49
- text; source indexes and heading metadata never replace the body. Long procedures and semantic
50
- judgment rules are published in the Context workflow bundle and loaded only
51
- when the current route or operation selects them.
74
+ Procedures, dialogue, diagnostics, schemas, source bodies, and generated views
75
+ are addressable workflow resources. Static resources use content digests;
76
+ dynamic views are tied to the workflow revision that selected them. Read
77
+ receipts can keep unchanged resources current within one conversation, but a
78
+ receipt never proves that an external action completed.
52
79
 
53
- Gate inspection and resolution Actions keep their own Skill and Schema
54
- locators. The Agent loads those conditional resources only when it enters that
55
- phase; they are not preloaded with the Route's ordinary required resources.
80
+ At a human Gate, inspection and resolution resources remain phase-local. The
81
+ Agent loads inspection material before a decision and resolution material only
82
+ after confirmation. This keeps the ordinary review path available without
83
+ preloading every possible decision surface.
56
84
 
57
- The two entry documents are also the source for hosts that expose Agent Skills
58
- instead of commands. There are no stage-specific skills: source, alignment,
59
- compile, review, and package guidance comes from the route-selected workflow
60
- resources.
85
+ ## Fully managed conversations
61
86
 
62
- ## Human gates and managed sessions
63
-
64
- Ordinary mode preserves source, read-permission, scope, structure, Review, and
65
- package decisions as explicit gates. Fully managed mode is available only when
66
- the user explicitly requests it in the current conversation:
67
-
68
- ```bash
69
- context status --managed --format json
70
- ```
71
-
72
- That session authority is not stored. It cannot choose source boundaries,
73
- authorize unread external content, perform external repository operations, or
74
- bypass validation and verification.
75
-
76
- After the initial managed status, consecutive deterministic routes can be
77
- collapsed with:
87
+ Fully managed operation is used only after the user explicitly authorizes it in
88
+ the current conversation. The Agent then starts with:
78
89
 
79
90
  ```bash
80
91
  context run --managed --until blocked-or-complete --format json
81
92
  ```
82
93
 
83
- The loop stops before any route that needs Agent interpretation, configuration,
84
- additional authority, or diagnostic repair, and returns the current workflow
85
- route for normal progressive loading.
86
-
87
- ## Workspace and SDK
94
+ The loop executes consecutive deterministic actions and Route-delegated Gates,
95
+ re-evaluating after every action. It stops before semantic reading, project
96
+ configuration, unresolved permission, diagnostic repair, or a non-unique plan.
97
+ Managed authority is never persisted or reused in another conversation.
88
98
 
89
- Run the plugin from the initialized Context project root. Project declarations
90
- live in `src/index.ts`; source state, draft state, approved knowledge, generated
91
- packages, and disposable runtime state remain owned by Context CLI.
99
+ ## Boundaries
92
100
 
93
- After workspace dependency installation, the SDK manual starts at:
101
+ - The plugin does not call an LLM; it is consumed by the host Agent.
102
+ - All workspace lifecycle writes go through Route-selected Context actions.
103
+ - It does not silently clone, fetch, checkout, install, build, test, or read
104
+ external content without the required authority.
105
+ - It does not duplicate workflow facts or lifecycle routing in the prompt.
106
+ - It keeps CLI tokens, paths, ids, flags, and `source_ref` values unchanged,
107
+ while explaining decisions in the user's current conversation language.
94
108
 
95
- ```text
96
- node_modules/@c4a/context/docs/README.md
97
- ```
109
+ ## Maintainer note
98
110
 
99
- The plugin does not expose source deletion, purge, or retraction. It also does
100
- not silently clone, fetch, checkout, install, build, test, or call an LLM.
111
+ `plugin/` is the only hand-maintained integration source. The build projects it
112
+ to Claude commands, Codex Skills, Cursor commands, and a Skill-only layout under
113
+ `dist/plugins`. Do not edit generated projections directly.
@@ -1,91 +1,96 @@
1
- # Context Plugin
1
+ # Context Agent 接入
2
2
 
3
- > [English version](./README.md)
3
+ [English](./README.md)
4
4
 
5
- <p align="center"><img src="./assets/logo.svg" alt="C4A Context" width="180"/></p>
5
+ <p align="center"><img src="./assets/logo.svg" alt="Context" width="180"/></p>
6
6
 
7
- Context 为项目内知识工作区提供轻量 Agent 入口。Plugin 不会把完整工作流塞进
8
- 一份提示词,而是先观察当前工作区事实,再由 Context CLI 选择当前步骤允许的
9
- 路线、命令、门禁以及 Markdown/schema 资源。
7
+ 这个插件是 Context 知识生产工作流的对话入口。用户向 Agent 说明知识目标,插件再
8
+ 把对话连接到本地 Context 运行时、当前工作区事实和 Route 选择的操作资源。
9
+
10
+ 插件有意只暴露一个精简入口,不为初始化、来源采集、审核和构建分别提供公开命令。
11
+ 详细工作流保存在运行时的 Provider bundle 中,可以依据当前事实按需选择、校验、
12
+ 测试和升级,而不会让入口 Prompt 越来越长。
13
+
14
+ ## 用户体验
15
+
16
+ 安装接入并刷新 Agent 宿主后,调用 Context 入口并说明期望知识:
17
+
18
+ ```text
19
+ /c4a:context 请把架构文档和当前仓库整理成可搜索的 Agent 知识包,保留来源证据,
20
+ 最终结构批准前先让我确认。
21
+ ```
22
+
23
+ 同一个入口可以初始化用户请求的工作区、定位已有工作区,或继续当前知识生产轮次。
24
+ Agent 在对话中解释用户决策,并使用运行时完成机械状态变更;用户不需要自行选择
25
+ 底层生命周期命令。
10
26
 
11
27
  ## 安装
12
28
 
29
+ 插件随 Context 运行时一起发布:
30
+
13
31
  ```bash
14
- npm i -g @c4a/context-cli
32
+ npm install -g @c4a/context-cli@latest
15
33
  context plugin install
16
34
  ```
17
35
 
18
- 源码开发模式需要先构建:
36
+ 从源码开发时,先构建再安装开发投影:
19
37
 
20
38
  ```bash
21
39
  bun run --filter @c4a/context-cli build
22
40
  context plugin install --dev
23
41
  ```
24
42
 
25
- 可用 `context plugin install --dry-run` 查看安装动作,用
26
- `context plugin path` 定位随 CLI 发布的 marketplace。
43
+ `context plugin install --dry-run` 可以预览宿主投影,`context plugin status`
44
+ 用于诊断安装。修改或重装插件后需要刷新 Agent 宿主。
27
45
 
28
- ## Agent 入口
46
+ ## 入口契约
29
47
 
30
- 公开入口保持精简:
48
+ 人工维护的源文件是 [`commands/context.md`](./commands/context.md),启动流程为:
31
49
 
32
- - `init`:创建 Context 工作区;
33
- - `continue`:观察并推进已有工作区。
50
+ 1. 运行只读的 `context entry --language <language> --format json`;
51
+ 2. 只执行它返回的 `next_action.command`;
52
+ 3. 工作区就绪后,将 `workflow.current` 视为当前步骤权威;
53
+ 4. 完整读取当前 Route 的所有必需资源;
54
+ 5. 只执行选中的动作或配置修改;
55
+ 6. 再次求值工作区。
34
56
 
35
- Continuation 从以下命令开始:
57
+ 入口不会根据周边文件自行推断工作区状态。只有用户明确请求或确认时才执行初始化;
58
+ 进入或求值已有工作区是只读行为。不存在 `context continue` primitive,也没有阶段
59
+ 专属的公开 Skill。
36
60
 
37
- ```bash
38
- context status --format json
39
- ```
61
+ ## 按需加载工作流上下文
40
62
 
41
- `workflow.current` 是当前步骤的权威协议。Agent 读取所有标记为
42
- `read_state: read-required` required 资源,只执行返回的命令,完整保留
43
- revision 与 authority 参数,并在每次动作后重新求值。当前会话可通过
44
- `context status --resource-receipts @<file>` 回传读取回执,使未变化资源标记为
45
- `current`。动态资源的 materialize 结果只有在 Agent 完整读取返回文件后才可作为
46
- 回执;`context.source-body/*` 是必须阅读的正文,source-index 和标题元数据不能
47
- 替代正文。
48
- 长篇流程与语义判断规则发布在 Context workflow bundle 中,仅在当前路线或操作
49
- 选中时加载。
63
+ 操作说明、对话、诊断、Schema、来源正文和生成 View 都是可寻址的工作流资源。
64
+ 静态资源使用内容 digest,动态 View 绑定选择它的 workflow revision。读取回执可以
65
+ 在同一对话中复用未变化资源,但不能证明外部动作已经完成。
50
66
 
51
- Gate 的检查动作与决议动作分别保留自己的 Skill Schema 位置。Agent 只在进入
52
- 相应阶段时加载这些条件资源,不会把它们提前混入 Route 的普通 required 资源。
67
+ 人工 Gate 的检查和决议资源保持阶段隔离:Agent 在决定前加载 inspection 内容,
68
+ 用户确认后才加载 resolution 内容。这样既保留普通审核能力,也不会预加载所有可能
69
+ 的决策界面。
53
70
 
54
- 这两个入口文档也用于生成仅支持 Agent Skills 的宿主入口。不再发布阶段型
55
- Skill;来源、对齐、编译、审核和构建说明均由当前路线选择的 workflow resources
56
- 动态提供。
71
+ ## 全托管对话
57
72
 
58
- ## 人工门禁与全托管会话
59
-
60
- 普通模式保留来源、读取权限、提取范围、结构、审阅和包形态等显式门禁。只有用户
61
- 在当前对话明确要求全托管时,才使用:
62
-
63
- ```bash
64
- context status --managed --format json
65
- ```
66
-
67
- 该会话权限不会持久化,也不能选择来源边界、授权尚未允许读取的外部内容、执行
68
- 外部仓库操作,或绕过校验与验证。
69
-
70
- 首次读取托管状态后,可用下面的命令合并连续的确定性步骤:
73
+ 只有用户在当前对话明确授权后,才使用全托管模式。Agent 从以下命令开始:
71
74
 
72
75
  ```bash
73
76
  context run --managed --until blocked-or-complete --format json
74
77
  ```
75
78
 
76
- 遇到需要 Agent 判断、配置修改、额外权限、诊断修复或多条命令的路线时,循环会
77
- 立即停止,并返回当前 `workflow.current` 供 Agent 按需加载上下文。
78
-
79
- ## 工作区与 SDK
79
+ 循环会执行连续的确定性动作和 Route-delegated Gate,并在每个动作后重新求值。遇到
80
+ 语义阅读、项目配置、未解决权限、诊断修复或非唯一计划时停止。全托管权限不会被
81
+ 持久化,也不能在另一场对话复用。
80
82
 
81
- Plugin 应在初始化后的 Context 项目根目录运行。`src/index.ts` 保存项目声明;
82
- 来源状态、草稿状态、已批准知识、构建产物和临时运行状态均由 Context CLI 管理。
83
+ ## 边界
83
84
 
84
- 安装工作区依赖后,SDK 手册入口为:
85
+ - 插件本身不调用 LLM,而是由宿主 Agent 消费。
86
+ - 所有工作区生命周期写入都通过 Route 选择的 Context Action 完成。
87
+ - 不会在缺少相应授权时静默 clone、fetch、checkout、install、build、test 或
88
+ 读取外部内容。
89
+ - 不在 Prompt 中复制工作流事实或生命周期路由。
90
+ - CLI token、路径、id、flag 和 `source_ref` 保持原样;面向用户的解释使用当前
91
+ 对话语言。
85
92
 
86
- ```text
87
- node_modules/@c4a/context/docs/README.md
88
- ```
93
+ ## 维护说明
89
94
 
90
- 当前 Plugin 不暴露 source 删除、purge 或 retraction,也不会静默执行 clone、
91
- fetchcheckoutinstall、build、test 或调用 LLM。
95
+ `plugin/` 是唯一人工维护的接入源。构建会将它投影为 `dist/plugins` 下的 Claude
96
+ commandsCodex SkillsCursor commands 和纯 Skill 目录。不要直接编辑生成投影。
package/plugins/VERSION CHANGED
@@ -1 +1 @@
1
- 0.6.7
1
+ 0.6.9