@c4a/context-cli 0.6.2 → 0.6.4

package/README.md

@@ -37,6 +37,11 @@ The public Agent entries are:
 For the shortest installed-package walkthrough, read
 [CLI Quickstart](./docs/quickstart.md).
 
+Workspace tracing is off by default. Use `context init context --debug` or
+`context debug enable` only when command and Agent Graph route observability is
+needed; logs stay under ignored `.tmp/context-runtime/debug/`. See
+[Workspace debug tracing](./docs/debug-tracing.md).
+
 ## CLI And Agent Responsibilities
 
 | Responsibility | Owner |
@@ -83,7 +88,8 @@ The workspace state is split across:
   confirmed structure snapshots during an open lifecycle round.
 - `knowledge/` for approved Markdown, the closed `structure.yaml` projection,
   and the minimal `decisions.json` rejected-candidate fingerprint map when one
-  exists.
+  exists. Resources referenced by approved pages live in content-addressed
+  `knowledge/assets/` paths.
 - `dist/` for generated package output.
 - `.tmp/context-runtime/` for other ignored logs, previews, reports, locks, and caches.
 
@@ -106,6 +112,14 @@ KB packages use flat, package-relative OKF roots: `wikis/`, `guides/`,
 `dist/<package-name>/` directory and is not repeated inside those roots. Older
 workspaces that still declare `distribution.knowledgeNamespace` remain
 loadable, but the legacy value no longer changes package paths.
+New KB setup should offer Git raw resource delivery first. Build rewrites links
+to repository raw URLs; committing and publishing the resources remains the
+package author's responsibility. An explicit `urlPrefix` also works when the
+Context workspace itself is outside Git. Without Git or an explicit prefix,
+authors can bundle resources under `others/assets/` or explicitly omit them and
+retain unresolved references.
+Bundled delivery may configure `kbPackage().assets.optimize`; Context itself
+does not depend on an image processor.
 
 See the SDK manuals for the complete configuration and template contract:
 
@@ -133,6 +147,21 @@ implementation detail; Context users and plugins consume only
 Building a package completes the currently active approved state; it does not
 freeze the workspace. New sources can be added and processed later.
 
+With explicit current-conversation managed authority,
+`context run --managed --until blocked-or-complete` keeps one workspace-bound
+runtime for consecutive deterministic actions. Each action remains bound to
+the Route revision that selected it; after the action, Context reloads the
+project from disk and evaluates the graph again. Known local actions run in the
+same process, while source tools and other external effects remain isolated in
+child processes.
+
+The runtime scope owns only short-lived resources such as output capture,
+timers, child processes, and write locks, and releases them in reverse order.
+Knowledge, snapshots, decisions, and package output are durable state: they
+retain their existing revision checks, project write lock, atomic write, close,
+and verify contracts. No execution scope rolls back or substitutes those
+contracts, and the workspace file protocol is unchanged.
+
 ## Command Groups
 
 ```bash
@@ -140,9 +169,14 @@ freeze the workspace. New sources can be added and processed later.
 context plugin install
 context plugin status
 
-# Workspace state
+# Workspace creation and state
 context init [project-dir]
 context status
+context run --managed --until blocked-or-complete --format json
+
+# Route-selected resources
+context resource materialize --help
+context resource acknowledge-current --help
 
 # Sources
 context source add repo [YYYYMMDD] --module <module> --local <repo-or-subdir>
@@ -161,15 +195,28 @@ context run <phase-id>
 context review html [collection] --open
 context review apply <payload-file>
 
+# Package template decisions
+context package template accept --help
+
 # Final quality and output
 context close
 context verify
 context build
+
+# Optional workspace tracing
+context debug enable
+context debug status
+context debug export
+
+# Development/cache maintenance
+context clean-cache --dry-run
 ```
 
 Run `context <command> --help` for current flags. Commands that require a
 workspace search upward for a `package.json` with `context.project=true` and a
-configured `context.entry`.
+configured `context.entry`. Revision-bound resource and package commands should
+normally be copied from `workflow.current`; the examples above show their
+discovery surface rather than a replacement for the current route.
 
 ## Human Gates And Evidence
 
@@ -195,6 +242,7 @@ citation: copy it exactly and do not parse it as a filesystem path.
 - [Getting Started](../context/docs/getting-started.md)
 - [Agent Guide](../context/docs/guides/agent-guide.md)
 - [Agent Dialogue](../context/docs/guides/agent-dialogue.md)
+- [Lark Resource Materialization](../context/docs/guides/lark-resources.md)
 - [Project API](../context/docs/reference/project-api.md)
 - [Package Templates](../context/docs/reference/package-templates.md)
 

package/README.zh-CN.md

@@ -26,6 +26,11 @@ context plugin install
 
 最简安装后流程参见 [CLI 快速开始](./docs/quickstart.md)。
 
+工作区调试追踪默认关闭。仅在需要观察命令调用与 Agent Graph 路由时，使用
+`context init context --debug` 或 `context debug enable` 开启；日志只写入已忽略的
+`.tmp/context-runtime/debug/`。协议与回放说明见
+[工作区调试追踪](./docs/debug-tracing.md)。
+
 ## CLI、Agent 和用户的分工
 
 | 职责 | 负责方 |
@@ -62,7 +67,7 @@ node_modules/@c4a/context/docs/reference/package-templates.md
 - `src/`：项目声明和知识包模板。
 - `sources/`：来源登记和已经读取的证据。
 - `.tmp/context-runtime/lifecycle/`：一个开放生命周期轮次中的、被忽略且仅由 CLI 管理的草稿候选和已确认结构快照。
-- `knowledge/`：已批准的 Markdown、close 后的 `structure.yaml` 结构投影，以及存在时用于记录被拒候选 fingerprint 的精简 `decisions.json`。
+- `knowledge/`：已批准的 Markdown、close 后的 `structure.yaml` 结构投影，以及存在时用于记录被拒候选 fingerprint 的精简 `decisions.json`。已批准页面引用的资源位于内容寻址的 `knowledge/assets/`。
 - `dist/`：构建生成的知识包。
 - `.tmp/context-runtime/`：其他被忽略的日志、预览、报告、锁和缓存。
 
@@ -76,6 +81,11 @@ node_modules/@c4a/context/docs/reference/package-templates.md
 `wikis/`、`guides/`、`rules/` 和 `feats/` 作为包内 OKF 根目录，不再在这些目录下重复包名。
 旧工作区即使仍声明 `distribution.knowledgeNamespace` 也可以继续加载，但该兼容字段不再改变
 知识包输出路径。
+新建 KB 时优先选择 Git raw 资源分发：构建器将链接改写到仓库 raw 地址；资源的
+提交和发布由知识包作者负责。非 Git 工作区可以配置另一个资源仓库的显式 Raw
+前缀；没有可用 Git 或显式前缀时，可以选择随包复制到 `others/assets/`，或显式
+不输出资源并保留失效引用。随包模式可以安装 `sharp` 并通过
+`kbPackage().assets.optimize` 仅优化生成文件；Context 本身不依赖图片处理器。
 
 完整配置和模板约定参见 SDK 手册：
 
@@ -99,6 +109,16 @@ node_modules/@c4a/context/docs/reference/package-templates.md
 
 一次构建只完成当前已经确认的知识状态，并不会冻结工作区。后续还可以继续添加和处理新的来源。
 
+当前对话明确授予全托管权限后，
+`context run --managed --until blocked-or-complete` 会在同一个工作区运行时中连续执行
+确定性动作。每个动作仍绑定到选择它的 Route revision；动作完成后，Context 会重新从磁盘
+加载项目并再次求值工作图。已知的本地动作在同一进程中执行，来源工具和其他外部副作用仍
+隔离在子进程中。
+
+执行作用域只管理输出捕获、定时器、子进程和写锁等短生命周期资源，并按注册顺序的逆序释放。
+知识、快照、审核决定和知识包产物属于持久状态，继续使用原有的 revision 校验、项目写锁、
+原子写入、close 和 verify 契约。执行作用域不会回滚或替代这些契约，工作区文件协议也不改变。
+
 ## 命令分组
 
 ```bash
@@ -106,9 +126,14 @@ node_modules/@c4a/context/docs/reference/package-templates.md
 context plugin install
 context plugin status
 
-# 工作区状态
+# 工作区创建与状态
 context init [project-dir]
 context status
+context run --managed --until blocked-or-complete --format json
+
+# 当前路由选择的资源
+context resource materialize --help
+context resource acknowledge-current --help
 
 # 知识来源
 context source add repo [YYYYMMDD] --module <module> --local <repo-or-subdir>
@@ -127,13 +152,27 @@ context run <phase-id>
 context review html [collection] --open
 context review apply <payload-file>
 
+# 知识包模板决策
+context package template accept --help
+
 # 最终质量与输出
 context close
 context verify
 context build
+
+# 可选的工作区调试追踪
+context debug enable
+context debug status
+context debug export
+
+# 开发与缓存维护
+context clean-cache --dry-run
 ```
 
-当前参数以 `context <command> --help` 为准。需要工作区的命令会向上查找带有 `context.project=true` 和 `context.entry` 配置的 `package.json`。
+当前参数以 `context <command> --help` 为准。需要工作区的命令会向上查找带有
+`context.project=true` 和 `context.entry` 配置的 `package.json`。带 revision
+约束的资源和知识包命令通常应直接复制 `workflow.current` 返回的命令；上面的例子只用于
+发现命令入口，不能替代当前路由。
 
 ## 人工门禁与证据
 
@@ -152,6 +191,7 @@ CLI 返回的来源名称、阶段 ID、候选 ID、诊断和 `source_ref` 都
 - [快速开始](../context/docs/getting-started.md)
 - [Agent 指南](../context/docs/guides/agent-guide.md)
 - [Agent 对话指南](../context/docs/guides/agent-dialogue.md)
+- [飞书资源物化](../context/docs/guides/lark-resources.md)
 - [项目 API](../context/docs/reference/project-api.md)
 - [知识包模板](../context/docs/reference/package-templates.md)