deepccc 0.2.24 → 0.2.26

package/docs/completion-session.md

@@ -0,0 +1,40 @@
+# Caller-owned completions
+
+`CompletionSession` is an opt-in stateless OpenAI-compatible transport. Pass the
+entire `messages` array; no system guidance, workspace files, skills, tools,
+history or compaction is injected. This is useful when comparing integrations
+without rewriting their established prompt builders.
+
+```js
+import {CompletionSession} from 'deepccc';
+const session = new CompletionSession({
+  apiKey: process.env.DEEPCCC_API_KEY,
+  baseURL: process.env.DEEPCCC_BASE_URL,
+  model: process.env.DEEPCCC_MODEL,
+});
+const result = await session.complete({
+  messages: [{role: 'system', content: 'Return JSON only.'},
+             {role: 'user', content: 'Return an object with ok=true.'}],
+  json: true, timeoutMs: 5000, maxOutputTokens: 256, temperature: 0.1,
+});
+if (result.status === 'success') console.log(result.content);
+```
+
+JSON mode sends `response_format: {type: 'json_object'}`; callers still parse,
+validate and authorize results. No local syntax repair or automatic retry is
+performed here. Completion is accepted only after a normal stop, never a length
+limit or interrupted stream. Text mode preserves plain-text output. Parallel
+calls do not share mutable history. `timeoutMs` covers stream consumption;
+optional cancellation is the second argument. Context/response character limits
+default to one million each. Oversize input and invalid options throw before
+network activity; runtime failures return fixed diagnostics without raw errors.
+
+JSON responses are collected as text without constructing partial objects for
+each streamed fragment. This avoids unnecessary parsing and allocation for large
+responses. Ordinary ChatSession, CLI and Web streaming behavior is unchanged.
+
+Optional `extensions` passes caller-supplied provider-specific JSON options.
+It cannot override messages, model, streaming, tool settings, response format,
+temperature or token limits. Keep credentials in config, not extensions. No
+messages, headers or generated content are logged or persisted by this class.
+Metrics include duration and request count. Remote cancellation is best effort.

package/docs/decision-session.md

@@ -1,192 +1,196 @@
-# Bounded structured decisions
-
-`DecisionSession` is an opt-in, programmatic, text-only API for integrations that
-own their state and need a bounded decision loop. Existing `ChatSession`, CLI and
-Web behavior is unchanged. The model client is reusable, but each `decide()` call
-starts with exactly the supplied context. No conversation history, workspace
-instructions, global skills, file tools, model-based compaction or raw stream
-logging is loaded automatically.
-
-This is not a simulator, a game-specific policy or a guarantee of model latency.
-Use an adapter to provide observations, validate decisions against current state,
-and execute actions. Keep application knowledge and private data outside the
-package. Read any skill references at application setup, then pass the relevant
-instructions through `systemPrompt`.
-
-## Minimal integration
-
-```js
-import { DecisionSession } from 'deepccc';
-import { jsonSchema } from 'ai';
-
-const outputSchema = jsonSchema({
-  type: 'object',
-  properties: { action: { type: 'string', enum: ['left', 'right', 'wait'] } },
-  required: ['action'],
-  additionalProperties: false,
-}, {
-  validate(value) {
-    if (value && typeof value === 'object' && !Array.isArray(value)
-        && Object.keys(value).length === 1
-        && ['left', 'right', 'wait'].includes(value.action)) {
-      return { success: true, value };
-    }
-    return { success: false, error: new Error('Invalid decision') };
-  },
-});
-
-const session = new DecisionSession({
-  model: process.env.DEEPCCC_MODEL,
-  effort: '', // Omit effort when the target service does not support it.
-  maxOutputTokens: 2048,
-}, {
-  systemPrompt: 'Choose a safe action toward the supplied goal. Unknown data stays unknown.',
-  outputSchema,
-  maxSteps: 1,
-  maxContextChars: 32000,
-});
-
-const result = await session.decide({
-  requestId: 'example-request-1',
-  stateVersion: 3,
-  timeoutMs: 5000,
-  context: {
-    observation: { position: 1, blocked: [0] },
-    goal: { position: 4 },
-    plan: null,
-    memory: [],
-  },
-});
-
-if (result.status === 'success') {
-  // Re-check result.stateVersion and legality in the adapter before execution.
-  console.log(result.value);
-} else {
-  console.log(result.status); // Never execute partial text as an action.
-}
-```
-
-The default Provider/model/credentials are resolved in the same way as
-`ChatSession`. This API always consumes a structured streaming response;
-`streaming` and `subModel` from ChatSession configuration are not decision options.
-There is no summarization call or hidden model switch.
-
-`outputSchema` and allowed tool input schemas **must contain runtime validators**.
-Use a Standard Schema supported by the AI SDK, or `jsonSchema(schema, {validate})`.
-A JSON schema alone describes the model contract but is not a runtime safety
-check, so the constructor rejects schemas without validators. Validators may be
-asynchronous and share the request deadline. The provider must support tool calls.
-The default `outputMode: 'tools'` uses the reserved `submit_result` tool; free-form
-JSON text is not accepted as an alternative in that mode.
-
-Since 0.2.24, `outputMode: 'json'` is available for OpenAI-compatible endpoints.
-It sends `response_format: {type: 'json_object'}` with no tools or tool choice;
-the schema is included in the system prompt and runtime validation is still
-mandatory. Nonempty `allowedTools` and other provider protocols are rejected in
-this mode. JSON syntax constraints do not guarantee semantic correctness.
-One local fallback removes trailing commas outside quoted strings, preserving
-values and escapes. Missing values, truncated streams, prose and invalid schemas
-are rejected; no extra model request is made for syntax recovery. Optional
-`metrics.jsonRepairs` counts repaired responses. Deadlines, cancellation, size
-limits, freshness checks and caller-owned context remain unchanged.
-
-## Explicit capabilities
-
-Supply a `tools` record with `description`, `inputSchema` and `execute`, and list
-the capabilities to expose in `allowedTools`. Supplying a tool does **not** enable
-it. Both default to empty. Tool names must begin with a letter and use only
-letters, digits or underscores (at most 64 characters); `submit_result` is reserved.
-
-```js
-const options = {
-  systemPrompt: 'Inspect relevant information only when needed, then submit a result.',
-  outputSchema,
-  maxSteps: 2, // one inspection step plus one final submission
-  maxToolCalls: 2,
-  allowedTools: ['inspect_state'],
-  tools: {
-    inspect_state: {
-      description: 'Return a compact observation for the supplied request.',
-      inputSchema: jsonSchema({ type: 'object', additionalProperties: false }, {
-        validate(value) {
-          return value && typeof value === 'object' && !Array.isArray(value)
-            && Object.keys(value).length === 0
-            ? { success: true, value }
-            : { success: false, error: new Error('Expected empty input') };
-        },
-      }),
-      async execute(input, { signal, requestId, stateVersion }) {
-        // Your adapter must honor signal and return a small JSON-serializable value.
-        return adapter.observe({ signal, requestId, stateVersion });
-      },
-    },
-  },
-};
-```
-
-The entire model tool batch is checked before any tool runs. Unknown names,
-invalid inputs, duplicate call IDs and mixing a final submission with other
-calls fail closed. Tools execute sequentially and receive the same cancellation
-signal and request identity. They are not given to the SDK for automatic execution.
-The last permitted model step must submit a result; it cannot start more tools.
-
-Prefer observation-only capabilities. A tool allowlist is not an OS sandbox.
-Register trusted code only. Cancellation cannot undo effects of a tool that already
-started. Idempotency, freshness and actual execution acknowledgements are adapter
-responsibilities. Returned identity allows the adapter to reject stale decisions;
-the core does not know whether external state has changed.
-
-## Budgets and results
-
-| Option | Default | Meaning |
-| --- | --- | --- |
-| request `timeoutMs` | Required | One wall-clock budget across generation, tools and validation |
-| `maxSteps` | 1 | Model requests, including final submission |
-| `maxToolCalls` | 4 | Total non-submission calls in a decision |
-| `maxContextChars` | 32000 | System prompt plus serialized messages |
-| `maxToolResultChars` | 8000 | Each serialized observation |
-| `maxResponseChars` | 32000 | Bounded streamed text/tool data; may count tool arguments twice |
-| model `maxOutputTokens` | Configured value, otherwise 2048 | Per-request provider output budget, including reasoning where applicable |
-
-Character budgets are protective size limits, not token estimates. Oversized
-state/results fail with `context_limit`; they are never silently truncated or
-summarized. Keep raw logs outside decision context. Assemble the latest state,
-active plan and selected evidence before calling the API. Background summaries
-should produce versioned memory snapshots rather than mutate an in-flight request.
-
-`success` is the only status carrying a validated `value`. Other statuses are
-`timed_out`, `cancelled`, `invalid_output`, `step_limit`, `tool_error`,
-`context_limit` and `error`. Metrics report total/model/tool milliseconds, model
-and tool call counts, and the last assembled context size. Provider/tool error
-payloads and partial generated content are not copied into result messages.
-Invalid configuration/request budgets throw before contacting the provider.
-
-Since 0.2.23, failures also include a safe `diagnostic` object with a fixed `code`
-and `stage`. Categories distinguish provider errors, invalid tool input, result
-schema failures, truncated output, interrupted output, deadlines and cancellation.
-Provider HTTP status is included when available, but error messages, raw tool
-arguments, prompts, headers and response bodies are never copied into diagnostics.
-The SDK's default raw error logging is disabled for this API. Integrations can
-record their own schema issue paths inside their validators; keep values and raw
-payloads out of those records. The original `status` remains the control-flow
-contract. Diagnostics do not relax validation or trigger automatic retries.
-
-Pass an optional `AbortSignal` as the second argument to `decide()`. Provider SDK
-automatic retries are disabled; any future application retry needs a fresh,
-explicit budget. Non-cooperative asynchronous tools/streams are raced against
-cancellation, and late results do not continue the decision loop. Cleanup is
-best-effort; it cannot guarantee remote inference billing stops or an external
-side effect is rolled back. Synchronous code that blocks the Node event loop
-cannot be preempted by a JavaScript timer: use a worker/process for heavy work.
-
-A deadline bounds waiting, not the probability of receiving a good result.
-Measure valid-result rate, median/p95 decision latency and application outcomes
-on the actual endpoint. Do not count a timeout as a fast successful decision.
-
-## Release checks
-
-Tests use synthetic states and a loopback model endpoint, never production data.
-For publication, inspect staged changes, outgoing commits and the actual packed
-archive (including compiled output), and review public PR/release text. Never put
-credentials, private endpoints, proprietary assets or application traces into
-examples, tests, documentation or package files.
+# Bounded structured decisions
+
+`DecisionSession` is an opt-in, programmatic, text-only API for integrations that
+own their state and need a bounded decision loop. Existing `ChatSession`, CLI and
+Web behavior is unchanged. The model client is reusable, but each `decide()` call
+starts with exactly the supplied context. No conversation history, workspace
+instructions, global skills, file tools, model-based compaction or raw stream
+logging is loaded automatically.
+
+This is not a simulator, a game-specific policy or a guarantee of model latency.
+Use an adapter to provide observations, validate decisions against current state,
+and execute actions. Keep application knowledge and private data outside the
+package. Read any skill references at application setup, then pass the relevant
+instructions through `systemPrompt`.
+
+## Minimal integration
+
+```js
+import { DecisionSession } from 'deepccc';
+import { jsonSchema } from 'ai';
+
+const outputSchema = jsonSchema({
+  type: 'object',
+  properties: { action: { type: 'string', enum: ['left', 'right', 'wait'] } },
+  required: ['action'],
+  additionalProperties: false,
+}, {
+  validate(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)
+        && Object.keys(value).length === 1
+        && ['left', 'right', 'wait'].includes(value.action)) {
+      return { success: true, value };
+    }
+    return { success: false, error: new Error('Invalid decision') };
+  },
+});
+
+const session = new DecisionSession({
+  model: process.env.DEEPCCC_MODEL,
+  effort: '', // Omit effort when the target service does not support it.
+  maxOutputTokens: 2048,
+}, {
+  systemPrompt: 'Choose a safe action toward the supplied goal. Unknown data stays unknown.',
+  outputSchema,
+  maxSteps: 1,
+  maxContextChars: 32000,
+});
+
+const result = await session.decide({
+  requestId: 'example-request-1',
+  stateVersion: 3,
+  timeoutMs: 5000,
+  context: {
+    observation: { position: 1, blocked: [0] },
+    goal: { position: 4 },
+    plan: null,
+    memory: [],
+  },
+});
+
+if (result.status === 'success') {
+  // Re-check result.stateVersion and legality in the adapter before execution.
+  console.log(result.value);
+} else {
+  console.log(result.status); // Never execute partial text as an action.
+}
+```
+
+The default Provider/model/credentials are resolved in the same way as
+`ChatSession`. This API always consumes a structured streaming response;
+`streaming` and `subModel` from ChatSession configuration are not decision options.
+There is no summarization call or hidden model switch.
+
+`outputSchema` and allowed tool input schemas **must contain runtime validators**.
+Use a Standard Schema supported by the AI SDK, or `jsonSchema(schema, {validate})`.
+A JSON schema alone describes the model contract but is not a runtime safety
+check, so the constructor rejects schemas without validators. Validators may be
+asynchronous and share the request deadline. The provider must support tool calls.
+The default `outputMode: 'tools'` uses the reserved `submit_result` tool; free-form
+JSON text is not accepted as an alternative in that mode.
+
+Since 0.2.24, `outputMode: 'json'` is available for OpenAI-compatible endpoints.
+It sends `response_format: {type: 'json_object'}` with no tools or tool choice;
+the schema is included in the system prompt and runtime validation is still
+mandatory. Nonempty `allowedTools` and other provider protocols are rejected in
+this mode. JSON syntax constraints do not guarantee semantic correctness.
+One local fallback removes trailing commas outside quoted strings, preserving
+values and escapes. Missing values, truncated streams, prose and invalid schemas
+are rejected; no extra model request is made for syntax recovery. Optional
+`metrics.jsonRepairs` counts repaired responses. Deadlines, cancellation, size
+limits, freshness checks and caller-owned context remain unchanged.
+
+JSON mode collects streamed text and parses the completed response once, rather
+than constructing intermediate partial objects. Final syntax recovery and schema
+validation remain mandatory. Tools mode and ordinary ChatSession are unchanged.
+
+## Explicit capabilities
+
+Supply a `tools` record with `description`, `inputSchema` and `execute`, and list
+the capabilities to expose in `allowedTools`. Supplying a tool does **not** enable
+it. Both default to empty. Tool names must begin with a letter and use only
+letters, digits or underscores (at most 64 characters); `submit_result` is reserved.
+
+```js
+const options = {
+  systemPrompt: 'Inspect relevant information only when needed, then submit a result.',
+  outputSchema,
+  maxSteps: 2, // one inspection step plus one final submission
+  maxToolCalls: 2,
+  allowedTools: ['inspect_state'],
+  tools: {
+    inspect_state: {
+      description: 'Return a compact observation for the supplied request.',
+      inputSchema: jsonSchema({ type: 'object', additionalProperties: false }, {
+        validate(value) {
+          return value && typeof value === 'object' && !Array.isArray(value)
+            && Object.keys(value).length === 0
+            ? { success: true, value }
+            : { success: false, error: new Error('Expected empty input') };
+        },
+      }),
+      async execute(input, { signal, requestId, stateVersion }) {
+        // Your adapter must honor signal and return a small JSON-serializable value.
+        return adapter.observe({ signal, requestId, stateVersion });
+      },
+    },
+  },
+};
+```
+
+The entire model tool batch is checked before any tool runs. Unknown names,
+invalid inputs, duplicate call IDs and mixing a final submission with other
+calls fail closed. Tools execute sequentially and receive the same cancellation
+signal and request identity. They are not given to the SDK for automatic execution.
+The last permitted model step must submit a result; it cannot start more tools.
+
+Prefer observation-only capabilities. A tool allowlist is not an OS sandbox.
+Register trusted code only. Cancellation cannot undo effects of a tool that already
+started. Idempotency, freshness and actual execution acknowledgements are adapter
+responsibilities. Returned identity allows the adapter to reject stale decisions;
+the core does not know whether external state has changed.
+
+## Budgets and results
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| request `timeoutMs` | Required | One wall-clock budget across generation, tools and validation |
+| `maxSteps` | 1 | Model requests, including final submission |
+| `maxToolCalls` | 4 | Total non-submission calls in a decision |
+| `maxContextChars` | 32000 | System prompt plus serialized messages |
+| `maxToolResultChars` | 8000 | Each serialized observation |
+| `maxResponseChars` | 32000 | Bounded streamed text/tool data; may count tool arguments twice |
+| model `maxOutputTokens` | Configured value, otherwise 2048 | Per-request provider output budget, including reasoning where applicable |
+
+Character budgets are protective size limits, not token estimates. Oversized
+state/results fail with `context_limit`; they are never silently truncated or
+summarized. Keep raw logs outside decision context. Assemble the latest state,
+active plan and selected evidence before calling the API. Background summaries
+should produce versioned memory snapshots rather than mutate an in-flight request.
+
+`success` is the only status carrying a validated `value`. Other statuses are
+`timed_out`, `cancelled`, `invalid_output`, `step_limit`, `tool_error`,
+`context_limit` and `error`. Metrics report total/model/tool milliseconds, model
+and tool call counts, and the last assembled context size. Provider/tool error
+payloads and partial generated content are not copied into result messages.
+Invalid configuration/request budgets throw before contacting the provider.
+
+Since 0.2.23, failures also include a safe `diagnostic` object with a fixed `code`
+and `stage`. Categories distinguish provider errors, invalid tool input, result
+schema failures, truncated output, interrupted output, deadlines and cancellation.
+Provider HTTP status is included when available, but error messages, raw tool
+arguments, prompts, headers and response bodies are never copied into diagnostics.
+The SDK's default raw error logging is disabled for this API. Integrations can
+record their own schema issue paths inside their validators; keep values and raw
+payloads out of those records. The original `status` remains the control-flow
+contract. Diagnostics do not relax validation or trigger automatic retries.
+
+Pass an optional `AbortSignal` as the second argument to `decide()`. Provider SDK
+automatic retries are disabled; any future application retry needs a fresh,
+explicit budget. Non-cooperative asynchronous tools/streams are raced against
+cancellation, and late results do not continue the decision loop. Cleanup is
+best-effort; it cannot guarantee remote inference billing stops or an external
+side effect is rolled back. Synchronous code that blocks the Node event loop
+cannot be preempted by a JavaScript timer: use a worker/process for heavy work.
+
+A deadline bounds waiting, not the probability of receiving a good result.
+Measure valid-result rate, median/p95 decision latency and application outcomes
+on the actual endpoint. Do not count a timeout as a fast successful decision.
+
+## Release checks
+
+Tests use synthetic states and a loopback model endpoint, never production data.
+For publication, inspect staged changes, outgoing commits and the actual packed
+archive (including compiled output), and review public PR/release text. Never put
+credentials, private endpoints, proprietary assets or application traces into
+examples, tests, documentation or package files.

package/docs/workspace-understanding.md

@@ -1,41 +1,41 @@
-# 项目理解与搜索
-
-DeepCCC CLI、Web 与 ChatCCC 内置 CCC 共用这些能力。无需配置向量服务、下载模型或修改项目指令文件；地图与证据保存在本机 `~/.deepccc/workspace-index/<工作目录哈希>/`。不在不同工作目录间自动合并知识（包括 worktree）。选入上下文的片段仍会随正常模型请求发送给用户配置的模型服务；“本地索引”不意味着模型请求离线。
-
-## 搜索范围不是权限边界
-
-- `search_code({query: "Policy"})`：默认 `project`，跳过常见依赖/构建目录及隐藏条目；ripgrep 还遵循 ignore 文件。
-- `search_code({query: "Policy", scope: "all"})`：包含依赖、隐藏及被忽略文件。不自动跟随目录符号链接，也不提升操作系统权限。
-- `search_code({query: "forward", path: ".venv/Lib/site-packages/example"})`：指定非工作目录根的路径时，缺省按 `all` 搜索。调用者可显式选择 `project`。
-- `scope`、`excluded`、`engine`、`warnings`、`truncated` 描述实际查询边界。无命中不证明项目中不存在相关能力。
-- Node 降级搜索支持相同的 project/all 范围切换，但不解析 `.gitignore`/`.ignore`，会明确返回警告；正则为 JavaScript 语法。正常路径优先使用内置 ripgrep，不拼接 shell 命令。
-
-明确指定文件时保留文件名输出，避免单文件命中被解析器丢弃。无效正则、超时、取消等不会伪装成正常无命中；降级路径跳过不可读条目时返回警告。
-
-## 有限预算的项目地图
-
-`workspace_map({query: "Policy", path: "可选目录", maxChars: 6000})` 提供文件清单、部分定义/导入/文档标题线索和证据笔记。支持 TS/JS、Python、Go、Rust、Java、C#、C/C++、Ruby、PHP 等文本线索；其他文件仍可按名称发现并用读取/搜索工具检查。
-
-这是**词法导航，不是 AST、完整调用图或语义向量索引**。定义优先于导入，查询相关片段优先展示。默认不遍历隐藏、虚拟环境或构建目录；可指定其目录生成地图。地图不解析 Git ignore 规则，这一点在输出中明确提示。JSON/TOML 配置值不作为符号片段展示；package.json 只提取有限的入口和脚本名称。
-
-每次刷新重新枚举并检查内容哈希，复用未变化文件的提取结果；能识别同长度修改、删除、新增及切换分支后的变化。默认上限为 1500 个目录/文件条目、约 2 秒扫描检查预算、8 MiB 已读源码，单文件 128 KiB。预算不是磁盘 I/O 的强制超时；网络挂载或慢盘可能超过此时间。超预算用 `partial` 表示；展示省略用 `displayTruncated` 表示。大仓库需要查询相关子目录，不能从部分地图得出全局否定结论。
-
-项目相关问题或“继续”类消息会自动获得最多 3000 字符的导航；其他任务随时可调用工具。识别属于轻量启发式，不保证覆盖所有问法。自动导航不进入持久化历史，避免每轮累加；缓存损坏或不可写时继续使用实时读取/搜索，不阻断对话。
-
-## 带来源的长期笔记
-
-`remember_project_fact({fact, path, excerpt})` 保存简短的项目能力/关系解释，以及当前文件中确实匹配的原文、SHA-256 和记录时间。证据文件必须位于当前工作目录内（解析符号链接后校验）。不可读、超大文件或不匹配原文会拒绝保存。
-
-笔记只存在用户缓存目录，独立于聊天摘要，因此可在压缩或重开会话后通过地图检索。同工作目录的会话共享笔记。展示前重新校验源文件；修改、删除或移动后旧笔记不再注入，但磁盘记录保留以便诊断。最多检查最近 20 条笔记，展示还受预算限制。请勿保存密钥、授权令牌、用户指令或未经证实的断言。
-
-原文匹配**只验证来源，不证明模型解释正确**；输出明确标注“agent interpretation”。针对同一文件和同一原文重新保存解释，会替换此前笔记。即使文件未变，相关配置/调用方也可能变化，重要决策仍需重新查证。压缩器会区分任务进度、已核实项目事实与推测，并优先保留纠正和源码入口。
-
-## 测试边界
-
-自动化测试覆盖依赖目录显式访问、搜索失败/无命中/截断、单文件输出解析、地图更新、证据失效、预算与取消，以及导航不会在历史中累积。这些是工具和上下文护栏，不是所有模型都能正确理解项目的保证；未对某个在线模型宣称准确率提升。
-
-## 长会话状态与轮内预算
-
-压缩器每次重写完整摘要，使用固定章节区分当前事实、仍待处理、已取代历史、项目事实、证据/推断/局限和重要操作。最近原始消息、明确纠正及当前磁盘事实优先；旧摘要中的助手评价不是事实或用户指令。旧格式摘要仍可读取，但在模型输入中会明确标记为历史材料，避免把已完成或回退的路线恢复成当前建议。
-
-同一轮 Agent 可能连续执行多个工具，AI SDK 会把先前结果重复发送到后续模型步骤。DeepCCC 在每一步前对这些结果执行结构保持的预算控制：每项最多约 24,000 字符，总量约 96,000 字符，最近 4 项优先。较早结果必要时替换为可识别的省略标记，assistant tool-call 与对应 `role: tool` 结果仍成对保留。该处理只影响本轮后续模型请求；用户界面事件、最终持久化记录和受独立上限保护的 raw stream log 不被这一步改写。需要细节时 Agent 应重新执行更聚焦的读取或搜索。
+# 项目理解与搜索
+
+DeepCCC CLI、Web 与 ChatCCC 内置 CCC 共用这些能力。无需配置向量服务、下载模型或修改项目指令文件；地图与证据保存在本机 `~/.deepccc/workspace-index/<工作目录哈希>/`。不在不同工作目录间自动合并知识（包括 worktree）。选入上下文的片段仍会随正常模型请求发送给用户配置的模型服务；“本地索引”不意味着模型请求离线。
+
+## 搜索范围不是权限边界
+
+- `search_code({query: "Policy"})`：默认 `project`，跳过常见依赖/构建目录及隐藏条目；ripgrep 还遵循 ignore 文件。
+- `search_code({query: "Policy", scope: "all"})`：包含依赖、隐藏及被忽略文件。不自动跟随目录符号链接，也不提升操作系统权限。
+- `search_code({query: "forward", path: ".venv/Lib/site-packages/example"})`：指定非工作目录根的路径时，缺省按 `all` 搜索。调用者可显式选择 `project`。
+- `scope`、`excluded`、`engine`、`warnings`、`truncated` 描述实际查询边界。无命中不证明项目中不存在相关能力。
+- Node 降级搜索支持相同的 project/all 范围切换，但不解析 `.gitignore`/`.ignore`，会明确返回警告；正则为 JavaScript 语法。正常路径优先使用内置 ripgrep，不拼接 shell 命令。
+
+明确指定文件时保留文件名输出，避免单文件命中被解析器丢弃。无效正则、超时、取消等不会伪装成正常无命中；降级路径跳过不可读条目时返回警告。
+
+## 有限预算的项目地图
+
+`workspace_map({query: "Policy", path: "可选目录", maxChars: 6000})` 提供文件清单、部分定义/导入/文档标题线索和证据笔记。支持 TS/JS、Python、Go、Rust、Java、C#、C/C++、Ruby、PHP 等文本线索；其他文件仍可按名称发现并用读取/搜索工具检查。
+
+这是**词法导航，不是 AST、完整调用图或语义向量索引**。定义优先于导入，查询相关片段优先展示。默认不遍历隐藏、虚拟环境或构建目录；可指定其目录生成地图。地图不解析 Git ignore 规则，这一点在输出中明确提示。JSON/TOML 配置值不作为符号片段展示；package.json 只提取有限的入口和脚本名称。
+
+每次刷新重新枚举并检查内容哈希，复用未变化文件的提取结果；能识别同长度修改、删除、新增及切换分支后的变化。默认上限为 1500 个目录/文件条目、约 2 秒扫描检查预算、8 MiB 已读源码，单文件 128 KiB。预算不是磁盘 I/O 的强制超时；网络挂载或慢盘可能超过此时间。超预算用 `partial` 表示；展示省略用 `displayTruncated` 表示。大仓库需要查询相关子目录，不能从部分地图得出全局否定结论。
+
+项目相关问题或“继续”类消息会自动获得最多 3000 字符的导航；其他任务随时可调用工具。识别属于轻量启发式，不保证覆盖所有问法。自动导航不进入持久化历史，避免每轮累加；缓存损坏或不可写时继续使用实时读取/搜索，不阻断对话。
+
+## 带来源的长期笔记
+
+`remember_project_fact({fact, path, excerpt})` 保存简短的项目能力/关系解释，以及当前文件中确实匹配的原文、SHA-256 和记录时间。证据文件必须位于当前工作目录内（解析符号链接后校验）。不可读、超大文件或不匹配原文会拒绝保存。
+
+笔记只存在用户缓存目录，独立于聊天摘要，因此可在压缩或重开会话后通过地图检索。同工作目录的会话共享笔记。展示前重新校验源文件；修改、删除或移动后旧笔记不再注入，但磁盘记录保留以便诊断。最多检查最近 20 条笔记，展示还受预算限制。请勿保存密钥、授权令牌、用户指令或未经证实的断言。
+
+原文匹配**只验证来源，不证明模型解释正确**；输出明确标注“agent interpretation”。针对同一文件和同一原文重新保存解释，会替换此前笔记。即使文件未变，相关配置/调用方也可能变化，重要决策仍需重新查证。压缩器会区分任务进度、已核实项目事实与推测，并优先保留纠正和源码入口。
+
+## 测试边界
+
+自动化测试覆盖依赖目录显式访问、搜索失败/无命中/截断、单文件输出解析、地图更新、证据失效、预算与取消，以及导航不会在历史中累积。这些是工具和上下文护栏，不是所有模型都能正确理解项目的保证；未对某个在线模型宣称准确率提升。
+
+## 长会话状态与轮内预算
+
+压缩器每次重写完整摘要，使用固定章节区分当前事实、仍待处理、已取代历史、项目事实、证据/推断/局限和重要操作。最近原始消息、明确纠正及当前磁盘事实优先；旧摘要中的助手评价不是事实或用户指令。旧格式摘要仍可读取，但在模型输入中会明确标记为历史材料，避免把已完成或回退的路线恢复成当前建议。
+
+同一轮 Agent 可能连续执行多个工具，AI SDK 会把先前结果重复发送到后续模型步骤。DeepCCC 在每一步前对这些结果执行结构保持的预算控制：每项最多约 24,000 字符，总量约 96,000 字符，最近 4 项优先。较早结果必要时替换为可识别的省略标记，assistant tool-call 与对应 `role: tool` 结果仍成对保留。该处理只影响本轮后续模型请求；用户界面事件、最终持久化记录和受独立上限保护的 raw stream log 不被这一步改写。需要细节时 Agent 应重新执行更聚焦的读取或搜索。

package/os-prompts/darwin.md

@@ -1,8 +1,8 @@
-## macOS 命令行提示
-
-你运行在 macOS 上。run_command 通过 zsh（POSIX shell）执行。引号遵循标准 POSIX 约定（与你在 bash 中已有的习惯相同）：
-
-- 双引号会被剥离并用于组合含空格参数：`echo "hello world"` 打印 `hello world`。
-- 单引号是字面量引用字符：`'a b'` 是单个参数 `a b`。
-- 反引号和 `$(...)` 执行命令替换；需要字面文本时请加引号。
-- 路径使用 `/` 分隔符，`~` 展开为主目录。
+## macOS 命令行提示
+
+你运行在 macOS 上。run_command 通过 zsh（POSIX shell）执行。引号遵循标准 POSIX 约定（与你在 bash 中已有的习惯相同）：
+
+- 双引号会被剥离并用于组合含空格参数：`echo "hello world"` 打印 `hello world`。
+- 单引号是字面量引用字符：`'a b'` 是单个参数 `a b`。
+- 反引号和 `$(...)` 执行命令替换；需要字面文本时请加引号。
+- 路径使用 `/` 分隔符，`~` 展开为主目录。

package/os-prompts/linux.md

@@ -1,8 +1,8 @@
-## Linux 命令行提示
-
-你运行在 Linux 上。run_command 通过 POSIX shell（bash/sh）执行。引语遵循标准 POSIX 约定（与你在 bash 中已有的习惯相同）：
-
-- 双引号会被剥离并用于组合含空格参数：`echo "hello world"` 打印 `hello world`。
-- 单引号是字面量引用字符：`'a b'` 是单个参数 `a b`。
-- 反引号和 `$(...)` 执行命令替换；需要字面文本时请加引号。
-- 路径使用 `/` 分隔符，`~` 展开为主目录。
+## Linux 命令行提示
+
+你运行在 Linux 上。run_command 通过 POSIX shell（bash/sh）执行。引语遵循标准 POSIX 约定（与你在 bash 中已有的习惯相同）：
+
+- 双引号会被剥离并用于组合含空格参数：`echo "hello world"` 打印 `hello world`。
+- 单引号是字面量引用字符：`'a b'` 是单个参数 `a b`。
+- 反引号和 `$(...)` 执行命令替换；需要字面文本时请加引号。
+- 路径使用 `/` 分隔符，`~` 展开为主目录。

package/os-prompts/win32.md

@@ -1,11 +1,11 @@
-## Windows 命令行提示
-
-你运行在 Windows 上。优先绕过 shell，只有需要 shell 运算符时才进入 cmd.exe：
-
-- 单个程序优先用 `run_process`，把可执行文件和每个参数分别放进 `executable` / `args`。它使用 `shell:false`，不会让 cmd.exe 再解释引号、反斜杠、`&`、`%VAR%` 等内容。
-- 多行或引号密集的 Python/Node 代码必须用 `run_script`。不要塞进 `python -c` / `node -e`；Windows 下复杂内联代码会被 `run_command` 拒绝，避免命令返回 0 却实际执行了不同代码。
-- `run_command` 仅用于 `&&`、管道、重定向等必须由 shell 解析的场景；它通过 cmd.exe 执行，不是 bash，也不是 PowerShell。
-- 双引号在 cmd.exe、Node 的 shell 封装和目标程序的 argv 解析之间会经历多层处理；是否保留或剥离取决于具体调用链，不能假设会“原样到达”。单引号在 cmd.exe 中不是可靠的引用字符。
-- 使用各命令工具的 `cwd` 参数切换工作目录，不要前置 `cd /d ... &&`。只有手工编写纯 cmd 命令时，跨盘 `cd` 才需要 `/d`。
-- PowerShell 专用语法（Get-Item、2>$null、Select-Object）不能直接写进 `run_command`；确需使用时，用 `run_process` 显式执行 `powershell.exe` 并逐项传参。
-- npm 11.x 在 Windows 上忽略 `--prefix` 对 `npm publish` 的作用。发布时把工具的 `cwd` 参数设为目标包目录，再执行 `npm publish`。
+## Windows 命令行提示
+
+你运行在 Windows 上。优先绕过 shell，只有需要 shell 运算符时才进入 cmd.exe：
+
+- 单个程序优先用 `run_process`，把可执行文件和每个参数分别放进 `executable` / `args`。它使用 `shell:false`，不会让 cmd.exe 再解释引号、反斜杠、`&`、`%VAR%` 等内容。
+- 多行或引号密集的 Python/Node 代码必须用 `run_script`。不要塞进 `python -c` / `node -e`；Windows 下复杂内联代码会被 `run_command` 拒绝，避免命令返回 0 却实际执行了不同代码。
+- `run_command` 仅用于 `&&`、管道、重定向等必须由 shell 解析的场景；它通过 cmd.exe 执行，不是 bash，也不是 PowerShell。
+- 双引号在 cmd.exe、Node 的 shell 封装和目标程序的 argv 解析之间会经历多层处理；是否保留或剥离取决于具体调用链，不能假设会“原样到达”。单引号在 cmd.exe 中不是可靠的引用字符。
+- 使用各命令工具的 `cwd` 参数切换工作目录，不要前置 `cd /d ... &&`。只有手工编写纯 cmd 命令时，跨盘 `cd` 才需要 `/d`。
+- PowerShell 专用语法（Get-Item、2>$null、Select-Object）不能直接写进 `run_command`；确需使用时，用 `run_process` 显式执行 `powershell.exe` 并逐项传参。
+- npm 11.x 在 Windows 上忽略 `--prefix` 对 `npm publish` 的作用。发布时把工具的 `cwd` 参数设为目标包目录，再执行 `npm publish`。