pi-ultracode 0.1.0 → 0.1.2

package/README.md

@@ -1,225 +1,478 @@
-# pi-ultracode
+# Ultracode
 
-> Claude-Code-style **ultracode** for [Pi](https://github.com/earendil-works/pi).
+**Ultracode** 是 [Pi](https://github.com/badlogic/pi-mono) 的“全力执行”模式。它把 Pi 的 Agentic Loop 从单线程编码助手升级为能够运行子代理团队的编排器。
 
-`ultracode` is an effort mode that turns Pi into a relentless, multi-agent
-orchestrator. While it's on, Pi raises its thinking to **xhigh** and treats
-"author and run a workflow" as the **default** for every substantive task —
-decomposing work, fanning it out across isolated subagents, and adversarially
-verifying findings before committing to an answer. Token cost is not the
-constraint; correctness and coverage are.
+启用 Ultracode 后，主代理会获得一条 `workflow` 工具，以及一段要求它主动使用该工具处理复杂任务的系统提示词。扩展加载时会先注册该工具，并在模型请求前的 input 与 `before_agent_start` 边界按模式校准 active tools；未启用或已暂停时，残留调用会被拒绝。每个子代理都运行在独立的内存 Pi 会话中，拥有标准编码工具、独立上下文，并可选择结构化输出、模型覆盖、Agent Type 和隔离的 git worktree。
 
-This single extension implements the full ultracode surface:
+Ultracode 保留 Pi 自身的核心循环、内存模型、工具系统、扩展 API 与会话格式。它是在 Pi 之上增加编排能力，而不是替换 Pi。
 
-| Pillar | What you get |
+## 功能
+
+| 能力 | 说明 |
 | --- | --- |
-| **Ultracode mode** | `/ultracode on` raises thinking to xhigh, keeps the `workflow` tool active, and injects a standing "orchestrate + verify by default" system block on every turn. Survives reload / resume / fork via session entries. Optional token budget. |
-| **The `workflow` tool** | A deterministic JavaScript orchestrator: `agent()`, `parallel()`, `pipeline()`, `phase()`, `log()`, `workflow()` (nesting), `args`, `budget`. Plus per-agent **model overrides**, **custom agent types**, **git-worktree isolation**, a real **token budget**, **resumable runs**, and **script persistence**. |
-| **`/workflows` manager** | List recent and in-flight runs with live progress; inspect or abort runs. |
+| `workflow` 工具 | 模型请求前按 Ultracode 状态校准；运行确定性的 JavaScript 编排脚本，并调用 `agent()`、`parallel()`、`pipeline()` 和 `workflow()`。 |
+| 独立子代理 | 每次 `agent()` 调用都会创建一条带标准编码工具的新 Pi 会话。 |
+| 并行执行 | `parallel()` 并发运行任务，且保留输入顺序。 |
+| 流水线 | `pipeline()` 让任务独立流经多个阶段，无需全局屏障。 |
+| 结构化输出 | 传入 JSON Schema，即可通过终止型 `structured_output` 工具获得经校验的对象。 |
+| Agent Type | 通过 `.pi/ultracode/agents/*.md` 定义角色提示词、工具白名单、模型和思考强度。 |
+| 模型覆盖 | 每次 `agent()` 调用都可指定模型模式，例如 `anthropic/claude-sonnet-4`。 |
+| Worktree 隔离 | 让写入型并行代理在临时 git worktree 中运行，并把改动安全合并回共享工作树。 |
+| 进度与详情 | 实时状态、实际模型/effort、turn/工具/token 统计，以及可流式展开的 TUI 任务详情浮层。 |
+| Ultracode 模式 | `/ultracode on` 启用主动编排提示词，并请求当前模型支持的最高思考强度。 |
+| 配额执行 | 可选 token 预算、代理数量限制、并发限制、脚本超时与嵌套深度限制。 |
+
+## 为什么使用工作流
+
+普通的多代理提示通常依赖模型临场决定如何分解与组合任务。Ultracode 采用另一种方式：**模型编写确定性的编排脚本，运行时执行该脚本**。
 
-Inspired by Anthropic's [dynamic workflows in Claude Code](https://claude.com/blog/introducing-dynamic-workflows-in-claude-code),
-and a superset of the `pi-dynamic-workflows` prototype.
+这样可以清晰表达：
 
-## Install
+- 哪些任务可以并行；
+- 哪些阶段依赖前一阶段的结果；
+- 哪些代理应返回结构化数据；
+- 何时需要共享上下文，何时需要隔离；
+- 预算如何限制额外探索；
+- 失败分支应如何降级。
+
+## 安装
 
 ```bash
 pi install npm:pi-ultracode      # or: pi install /path/to/pi-ultracode
 ```
 
-> **Conflict note:** pi-ultracode registers a tool named `workflow`, the same name
-> used by `pi-dynamic-workflows`. pi-ultracode is a strict superset, so remove the
-> prototype first: `pi remove npm:pi-dynamic-workflows`.
+> **工具冲突：** pi-ultracode 注册名为 `workflow` 的工具，与 `pi-dynamic-workflows` 相同。pi-ultracode 是后者的严格超集，请先执行 `pi remove npm:pi-dynamic-workflows` 移除原型扩展。
+
+安装后在 Pi 中运行 `/reload`。
+
+开发仓库也可直接加载：
+
+```bash
+pi -e ./extensions/ultracode.ts
+```
 
-Then in Pi: `/reload`.
+仓库中提供两个兼容入口：
 
-## Usage
+- `extensions/ultracode.ts`：推荐的 Pi 扩展入口；
+- `src/index.ts`：兼容入口，重新导出同一个扩展。
 
-### Turn ultracode on
+## 快速开始
+
+在 Pi 中启用模式：
+
+```text
+/ultracode on
+```
+
+随后给出复杂任务，例如：
 
 ```text
-/ultracode               # TOGGLE on/off
-/ultracode on            # xhigh thinking + default workflow orchestration
-/ultracode on 500k       # also cap the per-session output-token budget at ~500k
-/ultracode budget 1m     # change the budget later
-/ultracode status        # show current mode
-/ultracode off           # restore the previous thinking level
+Review the current branch, identify correctness and compatibility risks,
+fix the justified issues, and verify the result.
 ```
 
-> **Models without `xhigh`:** pi clamps the requested level down to the model's
-> maximum (e.g. glm-5.2 tops out at `high`; non-reasoning models fall to `off`) —
-> it never errors. `/ultracode status` shows the level that actually applied
-> (e.g. `ultracode: on · thinking high`). The **workflow orchestration** half of
-> ultracode doesn't depend on the thinking level at all, so it's unaffected by
-> the model you run.
+启用后，主代理会被要求在并行检视、迁移、审计或大范围修改明显有益时编写并运行工作流，而不是把所有工作塞进一个上下文。
 
-You can also start a session in ultracode mode with the CLI flag:
+也可以在启动时启用：
 
 ```bash
 pi --ultracode
 ```
 
-While on, just describe the task. Pi will write a workflow script and call the
-`workflow` tool, with live progress shown inline:
+工作流运行时会内联显示实时进度，例如：
 
 ```text
-◆ ▶ audit_repo (4/7 done, 2 running) · 3 cached · 41.2k/500k tok
+◆ ▶ audit_repo (4/7 done, 2 running) · 3 cached · 203k token (141k new, 62k replayed) · 41.2k/500k out
   ✓ Survey 1/1
     #1 ✓ repo inventory
+       gpt-5.6-sol • max · 15 turns · 42 tool uses · 141k token
   ▶ Review 3/4 · 1 running
     #2 ✓ auth module
     #3 ✓ db layer
     #4 ● payments module
+       claude-sonnet-4 • high · 6 turns · 18 tool uses · 52.3k+ token · partial
   ▶ Verify 0/2 · 2 running
 ```
 
-Press `Esc` to cancel; running subagents are aborted and surfaced as skipped.
+紧凑 token 数始终是 input + output；cache read/write 与成本只出现在任务详情中。主对话会折叠较早任务并明确显示省略数量，按 `Ctrl+O` 可展开全部，或用 `F6` 打开详情。按 `Esc` 可取消；运行中的子代理会被终止并显示为 cancelled，同时保留已有输出和部分用量。
 
-### Manage runs
+## 命令
 
 ```text
-/workflows               # toggle the run panel above the editor (run again to hide)
-/workflows wf_ab12-3     # show one run's detail
-/workflows clear         # hide the panel
-/workflows abort         # abort all active runs (and hide the panel)
+/ultracode             # toggle on/off
+/ultracode on          # enable orchestration mode
+/ultracode on 500k     # enable it with an output-token budget
+/ultracode off         # disable the tool and restore the previous thinking level
+/ultracode status      # show status and the configured budget
+/ultracode budget 500k # set a token budget
+/ultracode budget off  # remove the budget
+/workflows             # open the interactive workflow detail overlay
+/workflows <runId>     # open one run directly (prefix accepted)
+/workflows abort       # abort active runs
+F6                     # open the workflow detail overlay
 ```
 
-The panel is a static snapshot taken when you run the command, so re-run
-`/workflows` to refresh it, or `/workflows clear` to dismiss it. Live progress
-while a workflow runs is shown inline in the tool result, not in this panel.
+`/workflows` 与 `F6` 打开实时浮层。只有一个活动运行时会直接进入；多个活动运行会先显示选择器；没有活动运行时会打开最近完成的运行。宽终端使用任务/详情双栏，窄终端在列表与详情间切换。键盘操作：
+
+- `↑` / `↓` 选择运行或任务；`Enter` 打开；`Tab` 切换双栏焦点；`Esc` 返回或关闭；
+- `PageUp` / `PageDown` 滚动；`End` 恢复尾随；
+- `/` 搜索任务，`r` 只看运行中的任务，`a` 恢复全部，`p` 展开或收起任务 prompt。
 
-## Workflow script shape
+每次 `agent()` 调用都是一个可独立展开的任务。详情按时间交错显示 turn、assistant 正文、工具调用、重试、上下文压缩、错误与 thinking 持续时间；thinking 正文不会被捕获。正文 delta 只保存在有界内存中并以不超过每 100ms 一次的频率刷新，消息完成后改用 Markdown 渲染。
 
-A workflow is plain JavaScript whose first statement is a **pure literal**
-`export const meta`:
+所有可视化和落盘内容都会移除终端控制序列并脱敏凭据。内存上限为每任务 1MiB / 5000 行、每工作流 32MiB；最终 transcript 上限为每任务 10MB（约 1MB 头部 + 9MB 尾部）、每工作流 128MB。最终清理后的 timeline 与 manifest 保存在 session 的 `ultracode-runs/` 目录，因而 `/reload` 后仍可浏览；不会复制系统 prompt、注入 skill、AGENTS 内容或父会话上下文。
+
+状态行会显示实际生效的思考强度，例如：
+
+```text
+ultracode: on · max
+ultracode: on · xhigh
+ultracode: on · high
+ultracode: on · off
+```
+
+Ultracode 请求的是**当前模型支持的最高强度**，不是固定标签。对支持 `max` 的模型（包括 GPT-5.6 Sol）使用 `max`；能力较低的模型由 Pi 正常钳制。对不认识 `max` 的旧版 Pi，Ultracode 会自动回退到 `xhigh`。
+
+显式覆盖始终优先：
+
+- 每次调用的模型后缀，例如 `model: "openai/gpt-5.6-sol:high"`；
+- Agent Type frontmatter 中的 `thinking:`；
+- 显式 `:off`、`:high`、`:xhigh` 或 `:max`。
+
+模型切换或手动降低强度时，只要 Ultracode 仍启用，它就会重新请求该模型的最高可用强度。关闭或退出时，会恢复启用前的会话强度与原始默认偏好。若当前模型暂时无法表示原始强度，恢复意图会保留到后续兼容模型；中间模型的钳制结果不会覆盖原始意图。
+
+## 工作原理
+
+扩展注册单个 `workflow` 工具，并在 input preflight 与 `before_agent_start` 边界按 Ultracode 状态校准 active tools，同时保留其他 active tools。关闭或暂停时，`tool_call` 与实际执行入口会双重 fail-closed 拒绝残留调用。工具输入是 JavaScript 源码，其中必须包含纯字面量 `meta` 导出：
 
 ```js
 export const meta = {
-  name: 'review_changes',
-  description: 'Review changed files across dimensions, verify each finding',
-  phases: [{ title: 'Review' }, { title: 'Verify' }],
-}
+  name: "review_and_fix",
+  description: "Review independent areas, then verify the combined result",
+};
+```
+
+脚本可使用下列全局变量：
+
+- `agent(prompt, options)`
+- `parallel(thunks)`
+- `pipeline(items, ...stages)`
+- `phase(title)`
+- `log(message)`
+- `workflow(nameOrRef, args)`
+- `args`
+- `cwd`
+- `budget`
+
+`agent()` 的主要选项：
+
+| 选项 | 作用 |
+| --- | --- |
+| `label` | 进度中显示的 2–5 个词短名称。 |
+| `phase` | 显式指定进度阶段。 |
+| `schema` | 普通 JSON Schema；成功时返回经 `structured_output` 校验的对象。 |
+| `model` | 按模式覆盖模型，也可带 `:off`、`:high`、`:xhigh` 或 `:max`。 |
+| `agentType` | 使用内置或自定义角色。 |
+| `isolation: "worktree"` | 在临时 git worktree 中运行写入型代理。 |
+
+为保证可恢复和确定性，脚本不提供 Node.js 模块加载能力，也不允许直接使用 `fs`、网络、`Date.now()`、`new Date()` 或 `Math.random()`。
 
-const DIMENSIONS = [
-  { key: 'bugs', prompt: 'Find correctness bugs in the diff.' },
-  { key: 'perf', prompt: 'Find performance regressions in the diff.' },
-]
+### 取消与清理
+
+按 `Esc` 取消工作流时，取消信号会覆盖子代理初始化、异步 preflight 和流式执行窗口。运行器会等待进行中的 `abort()` 完成后再释放会话；清理失败不会覆盖原始 prompt 或取消错误。兼容旧版 Pi 时创建的临时 fallback 会话也遵循同一清理规则。
+
+### 直接调用
+
+```js
+export const meta = {
+  name: "single_review",
+  description: "Run one focused reviewer",
+};
+
+const result = await agent(
+  "Inspect src/mode.ts for lifecycle bugs. Return concise findings.",
+  { label: "mode review" },
+);
+
+export default result;
+```
+
+### 并行检视
+
+`parallel()` 接收 thunk，而不是已经启动的 Promise：
+
+```js
+export const meta = {
+  name: "parallel_review",
+  description: "Review independent concerns concurrently",
+};
+
+const tasks = [
+  ["correctness", "Review correctness and lifecycle behavior."],
+  ["tests", "Review test coverage and missing regressions."],
+  ["docs", "Review README and parity documentation."],
+];
+
+const results = await parallel(
+  tasks.map(([label, prompt]) => () => agent(prompt, { label })),
+);
+
+export default results.filter(Boolean);
+```
+
+### 流水线
+
+除非后续阶段确实需要所有前置结果，否则优先使用 `pipeline()`。不同条目可独立推进：
+
+```js
+export const meta = {
+  name: "review_pipeline",
+  description: "Inspect and verify several modules independently",
+};
+
+const files = ["src/mode.ts", "src/workflow/agent-runner.ts"];
 
-// pipeline: each dimension verifies as soon as its review completes (no barrier).
 const results = await pipeline(
-  DIMENSIONS,
-  (d) => agent(d.prompt, { label: 'review:' + d.key, phase: 'Review', schema: FINDINGS }),
-  (review) => parallel((review.findings ?? []).map((f) => () =>
-    agent('Adversarially verify, default to refuted: ' + f.title,
-      { label: 'verify:' + f.file, phase: 'Verify', agentType: 'code-reviewer', schema: VERDICT })
-      .then((v) => ({ ...f, verdict: v }))
-  )),
-)
+  files,
+  async (file) => agent(
+    `Inspect ${file} and report concrete risks.`,
+    { label: `inspect ${file}` },
+  ),
+  async (finding, file) => agent(
+    `Verify this finding against ${file}:\n\n${finding}`,
+    { label: `verify ${file}` },
+  ),
+);
+
+export default results.filter(Boolean);
+```
+
+### 结构化输出
 
-const confirmed = results.flat().filter(Boolean).filter((f) => f.verdict?.isReal)
-return { confirmed }
+不传 `schema` 时，`agent()` 返回子代理最后一段非空 assistant 文本；传入普通 JSON Schema 时，则返回经校验的对象：
 
-const FINDINGS = { type: 'object', properties: { findings: { type: 'array', items: { type: 'object' } } } }
-const VERDICT = { type: 'object', properties: { isReal: { type: 'boolean' }, why: { type: 'string' } }, required: ['isReal'] }
+```js
+export const meta = {
+  name: "structured_audit",
+  description: "Collect machine-readable findings",
+};
+
+const finding = await agent(
+  "Audit the mode lifecycle and return one finding.",
+  {
+    label: "lifecycle audit",
+    schema: {
+      type: "object",
+      properties: {
+        severity: { enum: ["low", "medium", "high"] },
+        summary: { type: "string" },
+      },
+      required: ["severity", "summary"],
+      additionalProperties: false,
+    },
+  },
+);
+
+export default finding;
 ```
 
-### Globals
+使用 schema 的代理必须调用 `structured_output`。否则该 `agent()` 分支会失败并返回 `null`；工作流本身仍可继续，因此脚本应过滤或显式处理失败分支，而不会把自由文本伪装成结构化结果。
 
-| Global | Description |
-| --- | --- |
-| `agent(prompt, opts)` | Spawn an isolated subagent. Returns its final text, or a validated object when `opts.schema` is set. |
-| `parallel(thunks)` | Run `() => agent(...)` thunks concurrently. **A barrier.** Failures become `null`. |
-| `pipeline(items, ...stages)` | Run each item through stages independently (no barrier). Stages get `(prev, original, index)`. **The default** for multi-stage work. |
-| `workflow(nameOrRef, args)` | Run a saved workflow (by name) or `{ scriptPath }` inline, sharing the run's concurrency cap, agent counter, and budget. One level of nesting. |
-| `phase(title)` | Mark the current progress group. |
-| `log(message)` | Append a workflow-level log line. |
-| `args`, `cwd` | The tool's `args` value; the working directory. |
-| `budget` | `{ total, spent(), remaining() }` — real output-token budget. |
-
-### `agent()` options
-
-| Option | Effect |
-| --- | --- |
-| `label` | Short (2-5 word) name shown in live progress. |
-| `phase` | Assign this agent to a progress group explicitly (use inside `parallel`/`pipeline`). |
-| `schema` | Plain JSON Schema; the subagent returns a validated object via a terminating `structured_output` tool. |
-| `model` | Override the subagent model by pattern, e.g. `'sonnet'` or `'provider/id:high'`. |
-| `agentType` | Use a custom role: built-ins `claude`, `general-purpose`, `Explore`, `Plan`, `code-reviewer`, or your own (below). |
-| `isolation: 'worktree'` | Run the agent in a throwaway git worktree (for parallel file mutation). Changes are applied back to the working tree under a lock; an unchanged worktree is auto-removed. |
+## Agent Type
 
-### Determinism
+项目级角色定义放在：
 
-Scripts run in a `vm` sandbox. `Date.now()`, `new Date()`, `Math.random()`,
-`require`/`import`, `fs`, and network APIs are unavailable — this keeps `meta`
-parseable and runs **reproducible and resumable**. Pass timestamps via `args`;
-vary randomness by agent index.
+```text
+.pi/ultracode/agents/*.md
+```
 
-## Custom agent types
+用户级角色定义放在：
 
-Drop a Markdown file with frontmatter under
-`.pi/ultracode/agents/<name>.md` (project) or `~/.pi/ultracode/agents/<name>.md`
-(user):
+```text
+~/.pi/ultracode/agents/*.md
+```
 
-```markdown
+同时兼容旧的用户级目录 `~/.pi/agent/agents/*.md`。
+
+示例：
+
+```md
 ---
-name: security
-description: Security-focused reviewer
-tools: read, grep, find, bash
-model: sonnet
+name: reviewer
+description: Read-only reviewer focused on correctness and regressions
+tools: read, bash
+model: anthropic/claude-sonnet-4
 thinking: high
 ---
-You are a security reviewer. Hunt for injection, authz gaps, and unsafe deserialization.
-Cite exact file:line evidence and prefer false negatives over invented findings.
+
+Inspect the requested area. Do not modify files. Report only evidence-backed findings.
 ```
 
-Then `agent('Audit auth.ts', { agentType: 'security' })`.
+工作流中的用法：
 
-## Saved & resumable runs
+```js
+await agent("Review the current diff.", {
+  label: "diff review",
+  agentType: "reviewer",
+});
+```
 
-Every run persists its script and a JSONL journal under
-`<sessionDir>/ultracode-runs/<runId>.{workflow.js,jsonl}`. To resume after a
-pause, kill, or script edit, call the tool again with `resumeFromRunId`: the
-longest unchanged prefix of `agent()` calls returns cached results instantly;
-the first changed/new call and everything after it run live.
+内置类型包括 `claude`、`general-purpose`、`Explore`、`Plan` 和 `code-reviewer`。
 
-Save reusable workflows under `.pi/ultracode/workflows/<name>.workflow.js` and
-run them with the tool's `name` parameter or `workflow('<name>')`.
+Agent Type 可控制：
 
-## Library modules
+- 角色提示词；
+- 工具白名单；
+- 默认模型；
+- 默认思考强度。
 
-| File | Purpose |
-| --- | --- |
-| `src/prompts.ts` | Ultracode system block + workflow tool guidelines. |
-| `src/mode.ts` | The ultracode mode controller (toggle, thinking, persistence, injection). |
-| `src/commands.ts` | `/ultracode` and `/workflows` commands. |
-| `src/workflow/parser.ts` | AST-validated, deterministic script parser. |
-| `src/workflow/runtime.ts` | The sandboxed runtime (agent/parallel/pipeline/phase/log/workflow/budget). |
-| `src/workflow/agent-runner.ts` | In-memory subagent runner (model, agent type, worktree, usage). |
-| `src/workflow/worktree.ts` | Git worktree isolation. |
-| `src/workflow/agent-types.ts` | Custom agent-type discovery. |
-| `src/workflow/journal.ts` | Run journal + resume. |
-| `src/workflow/registry.ts` | In-process run registry for `/workflows`. |
-| `src/workflow/display.ts` | Live progress snapshots and renderers. |
-| `src/workflow/structured-output.ts` / `json-schema.ts` | Terminating structured output + JSON-Schema → TypeBox. |
-| `src/workflow/tool.ts` | The Pi `workflow` tool. |
-| `extensions/ultracode.ts` | Extension entrypoint. |
-
-## Development
+每次调用的选项优先于 Agent Type 默认值。
+
+## 模型选择
+
+`model` 接受 provider/model 模式，并可带思考强度后缀：
+
+```js
+await agent("Analyze this failure.", {
+  label: "failure analysis",
+  model: "openai/gpt-5.6-sol:max",
+});
+```
+
+若未指定 model，则子代理继承工作流工具创建时的 Pi 当前模型。Ultracode 启用时，默认子代理强度同样请求 `max`，并按每个代理实际选择的模型独立钳制。Ultracode 不会自动启用 GPT-5.6 的 `pro` 模式，也不会隐式设置 token 预算。
+
+## Worktree 隔离
+
+并行写入同一工作树容易产生竞态。对会修改文件的代理使用：
+
+```js
+await agent("Implement the requested change and run focused tests.", {
+  label: "implementation",
+  isolation: "worktree",
+});
+```
+
+运行器会：
+
+1. 创建临时 git worktree；
+2. 在隔离目录运行代理；
+3. 捕获 worktree diff；
+4. 检查共享工作树是否漂移；
+5. 通过 `git apply --3way` 应用补丁；
+6. 在失败时保存 rescue patch；
+7. 成功且安全时清理临时 worktree。
+
+如果 diff 捕获、rescue 保存或补丁集成异常，运行器会故障安全地保留 worktree，并在日志中给出路径，避免丢失代理改动。确认内容后可手动恢复或删除；超过保留阈值的 Ultracode worktree 会由后续运行回收。
+
+使用隔离前，共享仓库必须处于干净状态。
+
+## 已保存的工作流与可恢复运行
+
+可复用工作流可放在：
+
+```text
+.pi/ultracode/workflows/<name>.workflow.js
+~/.pi/ultracode/workflows/<name>.workflow.js
+```
+
+可通过工具的 `name`、`scriptPath`，或脚本内调用来运行：
+
+```js
+await workflow("saved_workflow_name", { target: "src" });
+```
+
+嵌套限制为一层，且共享父运行的并发上限、代理计数与 token 预算。
+
+每次运行都会把脚本和 JSONL journal 保存到：
+
+```text
+<sessionDir>/ultracode-runs/<runId>.workflow.js
+<sessionDir>/ultracode-runs/<runId>.jsonl
+```
+
+暂停、终止或修改脚本后，可再次调用 `workflow` 工具并传入 `resumeFromRunId`。最长的未变 `agent()` 调用前缀会立即返回缓存结果；第一个变化或新增的调用及其后续调用会实时执行。
+
+## 预算与限制
+
+默认 token 预算为无限。只有显式配置后，`budget.total` 才是有限值。
+
+动态探索必须同时检查预算是否存在：
+
+```js
+while (budget.total && budget.remaining() > 50_000) {
+  // additional bounded exploration
+  break;
+}
+```
+
+若不检查 `budget.total`，无限预算下的 `remaining()` 是 `Infinity`，循环可能一直运行到代理数量上限。
+
+其他限制：
+
+- 最大代理数；
+- 最大并发数；
+- 工作流脚本超时；
+- 嵌套深度；
+- 结构化输出校验；
+- 静态禁止不确定性与危险全局变量。
+
+## 会话与兼容性
+
+Ultracode 模式状态通过自定义 session entry 持久化。恢复、reload、fork 和 `/tree` 导航都会按当前 branch 重新读取状态；被丢弃分支中的 entry 不会错误启用模式。旧版 Pi 或旧模型会把 `max` 兼容回退为 `xhigh`，而不会把未知值静默变成 `off`。
+
+扩展清理只管理自己的详情浮层、status 与运行状态，不会调用 Pi 的全局 `ui.clear()`，因此不会清除其他扩展的 UI。
+
+## 开发
+
+```bash
+npm ci
+npm run typecheck
+npm test
+npm pack --dry-run
+```
+
+项目源码位于：
+
+- `extensions/ultracode.ts`：扩展入口和 Pi 生命周期接线；
+- `src/mode.ts`：Ultracode 模式状态、恢复与强度管理；
+- `src/thinking.ts`：共享思考强度词汇与兼容性检测；
+- `src/workflow/`：脚本验证、运行时、子代理执行、worktree 和进度显示；
+- `test/`：单元、扩展和回归测试；
+- `docs/parity.md`：与原生 Pi 能力边界的说明。
+
+开发依赖会安装 TypeScript 和用于测试的 Pi peer 包；通过 `pi install` 加载正式包时，Pi 仍会提供这些 peer 依赖。
+
+## 发布
+
+npm 发布由 [`.github/workflows/publish-npm.yml`](.github/workflows/publish-npm.yml) 完成，使用 npm Trusted Publishing（OIDC），无需保存长期 `NPM_TOKEN`。
+
+首次使用前，在 npm 的 `pi-ultracode` 包设置中添加 GitHub Actions Trusted Publisher：
+
+- Organization or user：`ekil1100`
+- Repository：`pi-ultracode`
+- Workflow filename：`publish-npm.yml`
+- Environment name：`npm`
+- Allowed action：`npm publish`
+
+同时在 GitHub 仓库中创建名为 `npm` 的 Environment；可以按需增加审批人。正常发布无需打开 Actions 页面：
 
 ```bash
-npm test          # node --test over the parser, runtime, journal, agent types, mode, and extension
-npm run typecheck # tsc --noEmit (requires a local TypeScript)
+npm version patch # or: minor / major / 0.2.0-beta.1
+git push origin main --follow-tags
 ```
 
-The test suite injects a mock subagent runner, so it runs without a model. A
-faithful end-to-end check (real subagents) just calls `runWorkflow` with the
-default runner.
+`npm version` 会同步更新 `package.json` 和 `package-lock.json`，创建版本提交与 `v<version>` Tag；推送 Tag 后 CI 自动发布。稳定版本发布到 `latest`，预发布版本发布到 `next`。
+
+需要重试或指定其他 npm dist-tag 时，也可以在 Actions 中手动运行工作流；填写完全匹配 `package.json` 的版本，且只允许从 `main` 运行。
+
+工作流会校验 Tag 与包版本完全一致、确认版本尚未发布，并在正式发布前执行干净安装、测试和类型检查。
+
+## 设计原则
+
+Ultracode 的目标不是“尽可能多地启动代理”，而是：
 
-**Dependencies.** The only hard runtime dependency is `acorn`; Pi provides
-`typebox` and `@earendil-works/*` to extensions at load time. When running the
-node test runner directly (which has no Pi loader), link those peers into
-`node_modules/` — e.g. symlink them from your Pi install — alongside the
-real `acorn` that `pi install` / `npm install` provides.
+> 在任务确实适合拆分、并行、独立验证或跨上下文扩展时，使用确定性编排获得更高置信度；否则继续使用 Pi 简洁直接的单代理循环。
 
-## License
+## 许可证
 
 MIT