dsh-code-index 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to dsh-code-index are documented here.
 
+## 0.9.0 — Edit-ready Context Packs (unreleased)
+
+- `code_context` now includes bounded, whole-line source excerpts for primary declarations, strong callers/callees, imports, likely tests and changes. Overlapping current/base ranges are deduplicated independently. Large declarations degrade to changed-line windows, then signature-only metadata.
+- One final ContextPack DTO selects candidates before presentation; both text and serialized pack respect the normalized hard character budget. Default canonical output stays a string; explicit `outputFormat: pack` enables structured output.
+- Inclusion reasons remain separate from exact/import-scoped/name-only relationship provenance. Missing or stale evidence is reported rather than fabricated.
+- Git symbol classification now distinguishes added/modified/deleted against a frozen commit baseline, including the betaCaller addition regression. Ambiguous identity is unclassified; reliable file renames are retained, and symbol renames are not inferred.
+- Deterministic camel/snake, filename/path/signature terms, bounded graph neighborhoods, and clean-tree test seeds improve task selection. No BM25 or architecture rewrite.
+- Added executable context-quality contracts for task recall, source evidence, noise exclusion, budget, isolation, worktrees, freshness, overlap and classification.
+- Development target moves to matching DSH/dsh-tools `0.2.0-rc.2`. Full/compact surfaces, v0.8 configuration, Node 22/24, local-first behavior, and text calls remain supported. Public declaration files are now included in the package.
+- Synced English/Chinese product docs and added a reproducible 30-second recording of real local tool calls. Web Context Card is deferred pending real Agent/replay/navigation validation; no Card screenshot or benchmark claim is made.
+
+See `RELEASE_EVIDENCE_v0.9.0.md` for verified checks and release boundaries.
+
 ## 0.8.0 — 2026-09-23
 
 ### Added

package/README.md

@@ -5,11 +5,73 @@
 
 English | [中文](README.zh.md)
 
-Project-aware live structural context engine for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`). It is **task-aware**, **project-aware**, and **live**: local tree-sitter indexing, no API key, and no external service.
+**v0.9.0 — Edit-ready Context Packs**
 
-Fits a niche the ecosystem took a while to fill: alongside git/voice/browser/memory plugins, several code-intelligence plugins have appeared (graph-based, embedding-based), while this one stays deliberately **local-first** — in-process tree-sitter over WASM and local file observation, with no remote service, embedding API, or vector database.
+Give your [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) agent the bounded source context it needs to start a code task. One `code_context` call selects primary declarations, strong callers/callees, imports, current changes, and likely tests, with exact source ranges and reasons for inclusion. When evidence is missing, the pack says so.
 
-## What the model gets
+- **Source within budget:** complete declarations, then whole-line windows, then explicit signature-only fallback. Overlapping source lines are deduplicated; current and baseline excerpts stay separate.
+- **One selected pack:** text and opt-in structured output consume the same final ContextPack. Both stay within the default 5000-character cap.
+- **Evidence you can inspect:** inclusion reasons are separate from `exact` / `import-scoped` / `name-only` relationship provenance. No probability or confidence estimate is invented.
+- **Local and current:** isolated repo/worktree indexes, external add/change/delete freshness, no external indexing API key. Existing full/compact surfaces and v0.8 configuration remain supported.
+
+This checkout contains the v0.9 release candidate. It has not been published; an npm install still receives the latest published version. See [release evidence](RELEASE_EVIDENCE_v0.9.0.md).
+
+## On this page
+
+- [🚀 Quick start](#quick-start)
+- [🧭 Project isolation and live updates](#project-isolation-and-live-updates)
+- [👀 See it in action](#see-it-in-action)
+- [🧰 Tools](#tools)
+- [Configuration](#configuration)
+- [Supported languages](#supported-languages)
+- [How it works](#how-it-works)
+- [Known limitations](#known-limitations)
+- [Feedback](#feedback)
+
+## Quick start
+
+Requires Node 22/24 and a matching DSH `0.2.0-rc.2` host group. For this unreleased checkout, build and install locally from the repository root:
+
+```sh
+pnpm install
+pnpm build
+npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add .
+npx @deepseek-ai/dsh@0.2.0-rc.2 web
+```
+
+Use the published-package command in [Install](#install) only when you intend to install the registry version, with its matching host.
+
+## Project isolation and live updates
+
+```text
+Open repo A → search finds A's symbols
+Switch to repo B → search finds B's symbols, not A's
+Edit files outside DSH → the next query sees the change
+Switch back to A → A's context is still isolated
+```
+
+Each Git worktree gets its own index and change state. The plugin watches projects accessed by the session and checks file metadata on tool calls, so additions, edits, and deletions become visible without a manual rebuild.
+
+## See it in action
+
+[30-second recorded demo](assets/context-pack-demo.html) · [terminal recording](assets/context-pack-demo.cast)
+
+Download the HTML replay and open it locally, or play the cast with an asciinema-compatible player. Reproduce with `pnpm build`, then `node scripts/context-pack-demo.mjs`. The recording uses actual local tool calls in a tiny Git repository; it does not claim an Agent task-success or performance benchmark.
+
+`code_context({ task: "Explain loadConfig", budgetChars: 5000 })` returns source immediately. An excerpt from the recorded call:
+
+```text
+primary: loadConfig src/config.ts:1-3 [current]
+Reason: task names this symbol
+Source (complete):
+export function loadConfig(input: string) {
+  return input.trim()
+}
+```
+
+The demo then makes an external edit, shows added/modified/deleted declarations with separate current/base source, and requests a 500-character pack. Web Context Card is deferred until real Agent execution, replay, and file navigation can be verified on the matching RC. The existing text presentation remains usable.
+
+## Tools
 
 | Tool | Purpose |
 |---|---|
@@ -19,27 +81,18 @@ Fits a niche the ecosystem took a while to fill: alongside git/voice/browser/mem
 | `code_map` | Bounded ranked repo map (top files by symbol density + import-graph PageRank, key symbols + lines) |
 | `code_refs` | Trace a symbol through the call graph: callers (who calls it) and callees (what it calls), resolved to file:line |
 | `code_change_context` | Start from the working-tree or an explicit diff and return changed symbols, callers, import dependents, bounded impact paths, and likely tests |
-| `code_context` | Task-aware unified entry point: routes a plain-language task across search, repo map, call/import graph, change context, tests, and a hard character budget |
+| `code_context` | Edit-ready ContextPack: bounded source, reasons, relationships, changes/tests, gaps, and a hard budget; text by default |
 | `code_health` | Opt-in (`codeHealth: true`): circular dependencies (import cycles) and orphan modules |
 
 Plus an optional **auto-injected system prompt section** (`code-index:repo-map`, order 60): a compact ranked map selected from the active DSH session workspace. Set `autoInject: false` to disable and rely on the `code_map` tool only.
 
-## Project-aware live context
-
-```text
-Open repo A → code_context uses A
-Switch to repo B → code_context automatically uses B
-Edit repo B from VS Code → the next code_context sees the new state
-Switch back to repo A → A's symbols and Git changes remain isolated
-```
-
-Each Git worktree gets its own index and change state. The plugin keeps contexts for up to four recently used projects and watches only projects a session has accessed. Filesystem events are coalesced; tool calls also scan current file metadata and reparse changed files before returning context.
-
 ## Install
 
 Requires `dsh` (any install path — npx, npm, or source) and Node ≥ 22.
 
-The development compatibility target is `@deepseek-ai/dsh@0.1.7-alpha.2` / `@deepseek-ai/dsh-tools@0.1.7-alpha.2` (Node 22 and 24 CI matrix). The harness is still a preview API; confirm the actual Web install and lifecycle against the target DSH build before release.
+The development compatibility target is `@deepseek-ai/dsh@0.2.0-rc.2` / `@deepseek-ai/dsh-tools@0.2.0-rc.2` (Node 22 and 24 CI matrix). The DSH plugin surface is still a preview API, so upstream changes may require compatibility updates.
+
+v0.9 requires the matching `0.2.0-rc.2` tool runtime; the peer pin prevents fresh npm installs from selecting the older registry `latest` tag. Upgrade the host group together. The text/config/tool-surface compatibility above does not promise support for older DSH APIs.
 
 ```sh
 # from npm (prebuilt)
@@ -72,61 +125,29 @@ In a workspace session, ask the agent:
 
 No API key is needed to *index*; the model must of course be configured to call the tools.
 
-## Example (input → output)
-
-User prompt:
-
-> Which repo are we in? Run `code_map` first, then find where `extractSymbols` is defined.
-
-The agent calls the tools in turn:
-
-```
-code_map
-# repo map
-## src/extract.ts (14)
-  function extractSymbols(code, id) :121
-  function languageForFile(filePath) :37
-  ...
-
-code_search { query: "extractSymbols" }
-export function extractSymbols(code, id) — src/extract.ts:121
-```
+## More capabilities
 
 The index builds lazily on first use; later calls are served from the on-disk cache with mtime-incremental refresh.
 
 ### Call graph
 
-`code_refs` traces a symbol through the call graph — the run below is on this repo itself (`getIndex` is defined at `src/tools.ts:105`, called from 7 sites, and its callee resolves to `src/tools.ts:74`):
+`code_refs` traces definitions, callers, and callees. The following is an earlier real example of that existing tool, not a v0.9 Context Card:
 
-![code_refs on dsh-code-index: definitions, 7 callers with their enclosing function, and callees resolved to file:line](assets/code-refs-demo.png)
+![Earlier code_refs output](assets/code-refs-demo.png)
 
 ### Change-aware context
 
 `code_change_context` defaults to the current Git working tree against `HEAD`. It also accepts an inline unified diff, repo-relative `files`, or stable `symbols` IDs. Results are bounded and each inferred relationship carries a provenance label: `exact`, `import-scoped`, or `name-only`. Deletions and renames use the baseline ref when available; untracked non-ignored files are included in working-tree mode.
 
-### Task-aware context
+### Edit-ready Context Packs
 
-`code_context` is the high-level entry point for agents that have a task rather than a symbol query. The deterministic router recognizes change, symbol, architecture, test, exploration, and ambiguous tasks, then ranks existing primitives into one bounded package:
+`code_context` routes change, symbol, architecture, test, exploration, and ambiguous tasks. Deterministic camel/snake terms plus file/path/signature terms rank candidates; exact named symbols are retained before selection. Strong primary seeds find likely tests even on a clean tree. Graph neighborhoods are bounded. BM25 is not used.
 
-```text
-code_context { task: "Fix duplicate configuration loading during startup" }
-
-Task context — change
-Primary symbols:
-- [exact] function loadConfig() — src/config.ts:42
-Relevant files:
-- src/config.ts (current change)
-- src/bootstrap.ts (entry path)
-Relationships:
-- bootstrap → loadConfig at src/bootstrap.ts:18 [exact; explicit-import-binding]
-Current changes:
-- modified function loadConfig() src/config.ts:42 [exact]
-Likely affected tests:
-- tests/config.spec.ts
-Budget: 3720 / 5000 chars
-```
+`budgetChars` defaults to 5000 and is normalized to 300–20000; `maxFiles` defaults to 12 and `maxSymbols` to 10. Budget units are JavaScript string characters, not tokens or UTF-8 bytes. Both rendered text and serialized final pack must fit. Code is never cut mid-line to fill the cap. Very small budgets can leave only signatures or gaps; a repository identity that cannot fit produces an explicit error. Task display is summarized to 120 characters without affecting routing.
 
-The `budgetChars`, `maxFiles`, and `maxSymbols` arguments are optional. `code_context` does not call an external model or API; `exact`, `import-scoped`, and `name-only` provenance remains explicit for inferred relationships.
+The default canonical return remains a **string**. Request `outputFormat: "pack"` explicitly for the exported `ContextPack` DTO. Its `items` are already selected, with source `file/startLine/endLine/side/ref/mode/code`, `reason`, and separate relationship `resolution/provenance` where relevant. `budget.usedChars` accounts for text; `budget.packChars` accounts for serialized JSON. Render with `renderContextPack`; no hidden candidate list is exposed through the result.
+
+Git changes with a readable, frozen baseline commit classify declarations as added/modified/deleted. Reliable file renames remain supported. Unknown or ambiguous structural identity is `unclassified`; symbol renames are not guessed. Explicit `files`/`symbols` in `code_change_context` remain selection modes, not a proof of a Git modification.
 
 ## Configuration
 
@@ -166,7 +187,7 @@ TypeScript, JavaScript, Python, Go, Rust, Java, C++ and C (`.ts .tsx .mts .cts .
 - **Repo map** (`src/repomap.ts`): personalized PageRank over the import graph (teleport = per-file density share, so hub files that are themselves imported by other hubs rise above flat in-degree counting), seeded by the density-aware file score (class/interface/function weighted, test paths damped), top-N files, per-file symbol cap, hard char truncation.
 - **Call graph** (`src/refgraph.ts`): call sites extracted per file (per language, with their enclosing function) are resolved by name into callers and callees — `code_refs` exposes this directly, and `code_search` uses call fan-in as a ranking tie-break.
 - **Change context** (`src/change-context.ts`): maps Git hunks to stable symbols, then follows bounded provenance-labeled callers, import dependents, entry paths, impact, and likely affected tests without returning the whole repository.
-- **Task-aware context** (`src/context.ts`): deterministically routes a task across the existing search, map, call graph, change context, and test signals, then deduplicates and trims them to a hard character budget.
+- **ContextPack** (`src/context.ts`, `src/context-pack.ts`, `src/source-excerpts.ts`): ranks task candidates, reads ephemeral source evidence, selects a final DTO under text/JSON budgets, then renders only selected items.
 - **Health** (`src/health.ts`): Tarjan SCC over the import graph yields circular dependencies; orphan-module detection lists symbol-bearing files with no inbound or outbound imports (entry points and tests excluded).
 - **Workspace resolution**: each tool resolves the session cwd (`agent.session.header.cwd`) and walks up to the nearest `.git` (bounded — a directory without a repo marker is never indexed).
 - **Project contexts** (`src/repo-context.ts`): canonical real paths identify separate worktrees; up to four contexts are retained. Each tool call scans current metadata and reparses only changed files, while the watcher refreshes dirty files after a bounded debounce.
@@ -177,10 +198,9 @@ TypeScript, JavaScript, Python, Go, Rust, Java, C++ and C (`.ts .tsx .mts .cts .
 - **web-tree-sitter pinned to `^0.25` (ESM)** — the 0.25 line uses ESM named exports (`Language`/`Query`); this pairing with `tree-sitter-wasms` static builds is verified working under Node ≥ 22/24.
 - Auto-injected maps use DSH's system-prompt assembly context for the active session. Agentless assembly falls back to the DSH process working directory. A newly accessed project may have an empty map on its first prompt while indexing completes; following assemblies receive its map.
 - The watcher starts only for projects accessed by a tool and is disposed with the plugin. With `externalWatch: false`, per-call metadata scans still detect ordinary mtime changes.
-- The preview DSH API is typechecked and exercised through package-level lifecycle fakes; a real DSH Web install/enable/disable run is a separate release gate.
 - Large monorepos still require a directory metadata scan on each tool call. File parsing is incremental, but scan latency depends on repository size and storage speed.
-- Local variables are indexed too — recall over precision; `code_search` ranking keeps them low.
-- Developer-preview harness: expect breaking harness/plugin API changes upstream.
+- Function-local variables are excluded. Module declarations and class members are indexed; a parser/graph is not a type checker.
+- Source reads reject files changed after the index snapshot, paths resolving outside the root, and current files over 1 MB. Signature-only fallbacks and gaps identify missing evidence; likely tests are leads, not proof of coverage.
 
 ## Development
 
@@ -205,8 +225,11 @@ It re-points every dead link at its real `.pnpm` store entry as a junction; safe
 
 ## Feedback
 
-Found a bug, or the map ranks something badly? Please [open an issue](https://github.com/lemonxiny55/dsh-code-index/issues) — real-world usage reports (repos where the ranking misbehaves, languages you want next) directly drive the roadmap.
+Used dsh-code-index? Tell me what helped, what broke, or what context it missed. Reply in the [official DSH plugin discussion](https://github.com/deepseek-ai/deepseek-harness/discussions/5623), or use the [feedback issue form](https://github.com/lemonxiny55/dsh-code-index/issues/new?template=feedback.yml) if issue submissions are enabled for the repository.
+
+To make a report actionable, include the approximate repository size and languages, the task you tried, the context you expected, and what the agent actually received. Mention whether project switching, a worktree, or an external file edit was involved. Please do not include private source code, credentials, or API keys.
 
 ## License
 
 MIT. Not affiliated with DeepSeek; built on the public `dsh` plugin surface.
+

package/README.zh.md

@@ -2,11 +2,73 @@
 
 [English](README.md) | 中文
 
-面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`) 的项目感知实时结构化上下文引擎。它具备**任务感知、项目感知、实时更新**能力:本地 tree-sitter 索引,无需 API key 或外部服务。
+**v0.9.0 — Edit-ready Context Packs**
 
-在一个生态姗姗来迟的细分领域占位:git/语音/浏览器/记忆类插件之外,代码智能方向的插件已陆续出现(图谱路线、向量嵌入路线),而本插件刻意保持**本地优先**——进程内 tree-sitter WASM 与本地文件观察,不连接远程服务、embedding API 或向量数据库。
+让 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Agent 用一次 `code_context` 调用拿到开始处理任务所需的有界源码上下文：主要声明、强相关 caller/callee、imports、当前变化和相关测试。每个关键 item 都有入选理由，源码有准确行号；证据不足时明确说明缺口。
 
-## 模型能得到什么
+- **预算内直接给源码：**完整声明 → 整行窗口 → 明确的 signature-only 降级。重叠源码行去重，current/base 分开。
+- **唯一最终 pack：**文本与显式 structured output 都基于预算选择后的 ContextPack；默认硬上限 5000 字符。
+- **可检查的证据：**入选 reason 与关系的 `exact` / `import-scoped` / `name-only` provenance 分开，不编造概率或 confidence。
+- **本地、隔离、实时：**repo/worktree 独立，外部增改删自动刷新，不需要外部索引 API key；保留 full/compact surface 和 v0.8 配置。
+
+当前 checkout 是 v0.9 发布候选，尚未发布；npm 安装得到的仍是最新已发布版本。验证边界见[release evidence](RELEASE_EVIDENCE_v0.9.0.md)。
+
+## 本页导航
+
+- [🚀 快速开始](#快速开始)
+- [🧭 项目隔离与实时更新](#项目隔离与实时更新)
+- [👀 实际效果](#实际效果)
+- [🧰 工具一览](#工具一览)
+- [配置](#配置)
+- [支持的语言](#支持的语言)
+- [工作原理](#工作原理)
+- [已知限制](#已知限制)
+- [反馈](#反馈)
+
+## 快速开始
+
+需要 Node 22/24 与匹配的 DSH `0.2.0-rc.2` 宿主版本组。当前版本尚未发布，在仓库根目录构建并本地安装：
+
+```sh
+pnpm install
+pnpm build
+npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add .
+npx @deepseek-ai/dsh@0.2.0-rc.2 web
+```
+
+只有想安装 registry 已发布版本时，才使用[安装说明](#安装)中的 npm 包命令，并匹配该版本的宿主。
+
+## 项目隔离与实时更新
+
+```text
+打开仓库 A → 搜索到 A 的符号
+切换到仓库 B → 搜索到 B 的符号,不会混入 A
+从 DSH 外部修改文件 → 下一次查询看到变化
+切回 A → A 的上下文仍然独立
+```
+
+每个 Git worktree 都有独立索引和变更状态。插件会监听会话访问过的项目,并在工具调用时检查文件元数据,因此新增、修改和删除都会自动反映到后续查询,无需手动重建。
+
+## 实际效果
+
+[30 秒真实调用回放](assets/context-pack-demo.html) · [终端录制](assets/context-pack-demo.cast)
+
+下载 HTML 后本地打开，或使用兼容 asciinema 的播放器。复现方式：`pnpm build`，再运行 `node scripts/context-pack-demo.mjs`。录制内容是在小型 Git 仓库中的实际本地工具调用，不代表 Agent 任务成功率或性能 benchmark。
+
+`code_context({ task: "Explain loadConfig", budgetChars: 5000 })` 直接返回源码。以下摘自实际录制输出：
+
+```text
+primary: loadConfig src/config.ts:1-3 [current]
+Reason: task names this symbol
+Source (complete):
+export function loadConfig(input: string) {
+  return input.trim()
+}
+```
+
+随后 demo 从外部修改文件，展示 added/modified/deleted 及独立的 current/base 源码，再请求 500 字符预算。Web Context Card 延期，等待匹配 RC 上真实 Agent 调用、replay 和文件跳转验证；既有文本展示继续可用。
+
+## 工具一览
 
 | 工具 | 用途 |
 |---|---|
@@ -16,27 +78,18 @@
 | `code_map` | 限量排名仓库地图(按符号密度 + import 图 PageRank 取核心文件 + 关键符号与行号) |
 | `code_refs` | 沿调用图追踪符号:callers(谁调用了它)与 callees(它调用了谁),解析到 file:line |
 | `code_change_context` | 从工作区或显式 diff 出发,返回变更符号、调用者、import 依赖、有限影响路径和可能受影响的测试 |
-| `code_context` | 任务感知的统一入口:根据自然语言任务组合搜索、仓库地图、调用/import 图、变更上下文、测试和字符预算 |
+| `code_context` | Edit-ready ContextPack：有界源码、理由、关系、变化/测试、缺口和硬预算，默认文本返回 |
 | `code_health` | 可选开启(`codeHealth: true`):环依赖(import 环)与孤儿模块 |
 
 外加一个可选的**自动注入系统提示词段**(`code-index:repo-map`,序 60):自动选择当前 DSH 会话工作区的精简排名地图。将 `autoInject: false` 可关闭,只依赖 `code_map` 工具。
 
-## 项目感知实时上下文
-
-```text
-打开仓库 A → code_context 使用 A
-切换到仓库 B → code_context 自动改用 B
-从 VS Code 修改仓库 B → 下一次 code_context 看到最新状态
-切回仓库 A → A 的符号与 Git 变更仍然独立
-```
-
-每个 Git worktree 都有独立索引和变更状态。插件最多保留最近使用的四个项目上下文,只监听会话访问过的项目。文件事件会合并处理;工具调用也会扫描当前文件元数据,并在返回上下文前重解析已变更文件。
-
 ## 安装
 
 需要 `dsh`(任意安装方式——npx、npm 或源码)与 Node ≥ 22。
 
-当前开发兼容目标为 `@deepseek-ai/dsh@0.1.7-alpha.2` / `@deepseek-ai/dsh-tools@0.1.7-alpha.2`(CI 覆盖 Node 22 和 24)。Harness 仍属于预览 API;发布前还需在对应 DSH 构建中确认真实 Web 安装与插件生命周期。
+当前开发兼容目标为 `@deepseek-ai/dsh@0.2.0-rc.2` / `@deepseek-ai/dsh-tools@0.2.0-rc.2`(CI 覆盖 Node 22 和 24)。DSH 插件接口仍属于预览 API,上游变化可能需要更新兼容适配。
+
+v0.9 要求匹配的 `0.2.0-rc.2` tools runtime；精确 peer pin 防止 npm 新安装选到 registry 中旧的 `latest` 标签。宿主版本组需一起升级；文本、配置、工具 surface 的兼容承诺不等于支持旧 DSH API。
 
 ```sh
 # 从 npm(预编译)
@@ -69,41 +122,29 @@ npx @deepseek-ai/dsh plugin --profile web add ./dsh-code-index
 
 *索引*本身不需要 API key;模型当然要配置好才能调用这些工具。
 
-## 示例(输入 → 输出)
-
-用户提示:
-
-> 我们现在在哪个仓库?先跑 `code_map`,然后找出 `extractSymbols` 定义在哪。
-
-agent 依次调用工具:
-
-```
-code_map
-# repo map
-## src/extract.ts (14)
-  function extractSymbols(code, id) :121
-  function languageForFile(filePath) :37
-  ...
-
-code_search { query: "extractSymbols" }
-export function extractSymbols(code, id) — src/extract.ts:121
-```
+## 更多能力
 
 索引在首次使用时惰性构建;后续调用由磁盘缓存提供,并按 mtime 增量刷新。
 
 ### 调用图
 
-`code_refs` 沿调用图追踪符号——下例直接跑在本仓库自身(`getIndex` 定义于 `src/tools.ts:105`,有 7 个调用点,其 callee 解析到 `src/tools.ts:74`):
+`code_refs` 追踪定义、调用者和被调用者。以下是既有工具的较早真实示例，不是 v0.9 Context Card：
 
-![在本仓库上运行 code_refs:定义、7 个带所属函数的调用点,以及解析到 file:line 的 callees](assets/code-refs-demo.png)
+![较早的 code_refs 输出](assets/code-refs-demo.png)
 
 ### 变更感知上下文
 
 `code_change_context` 默认分析相对于 `HEAD` 的当前 Git 工作区,也支持内联 unified diff、仓库相对 `files` 或稳定的 `symbols` ID。结果有数量和字符预算,每条推导关系都会标注 `exact`、`import-scoped` 或 `name-only` 来源。删除和重命名在可用时读取 baseline;工作区模式也会包含未被忽略的未跟踪源码文件。
 
-### 任务感知上下文
+### Edit-ready Context Packs
+
+`code_context` 识别修改、符号、架构、测试、探索和模糊任务。用 camel/snake 分词及文件名、路径、签名 terms 做确定性候选排序，保留 exact symbol；从强 primary seed 找 clean-tree likely tests，图邻域有界。不使用 BM25。
+
+`budgetChars` 默认 5000，规范化到 300–20000；`maxFiles` 默认 12，`maxSymbols` 默认 10。预算按 JavaScript 字符串字符计，不是 token 或 UTF-8 字节。文本和最终 pack 的 JSON 都必须满足上限，不切断代码行。小预算可能只剩签名或缺口；仓库身份本身无法放入预算时返回明确错误。展示任务摘要最多 120 字符，不影响路由。
 
-`code_context` 是 Agent 面对“代码任务”而不是单个符号时的高级入口。确定性的路由器识别修改、符号、架构、测试、探索和模糊任务,然后把已有能力合并、排序、去重并限制在字符预算内。只传 `task` 即可,也可以覆盖 `budgetChars`、`maxFiles`、`maxSymbols`。它不调用外部模型/API,推导关系的 `exact`、`import-scoped`、`name-only` provenance 会继续保留。
+默认 canonical return 保持 **string**。显式传 `outputFormat: "pack"` 才返回导出的 `ContextPack` DTO。`items` 已经过预算选择，源码字段为 `file/startLine/endLine/side/ref/mode/code`，同时有 `reason` 及适用的独立关系 `resolution/provenance`。`budget.usedChars` 对应文本，`budget.packChars` 对应 JSON；用 `renderContextPack` 渲染，不暴露隐藏候选列表。
+
+Git 变化使用固定的 baseline commit 判定 added/modified/deleted，保留可靠文件 rename。结构身份不明确或 baseline 缺失时为 `unclassified`，不猜 symbol rename。`code_change_context` 的显式 `files`/`symbols` 仍是选择模式，不构成 Git modified 的证据。
 
 ## 配置
 
@@ -143,7 +184,7 @@ TypeScript、JavaScript、Python、Go、Rust、Java、C++、C(`.ts .tsx .mts .ct
 - **仓库地图**(`src/repomap.ts`):import 图上的个性化 PageRank(传送向量 = 各文件密度份额,被其他枢纽文件引用的枢纽会比平铺入度统计排得更靠前),以密度感知的文件打分为底(class/interface/function 加权,测试路径衰减),取 Top-N 文件,每文件符号上限,硬截断。
 - **调用图**(`src/refgraph.ts`):逐文件提取调用点(按语言,并记录其所属函数),按名称解析成 callers 与 callees——`code_refs` 直接暴露,`code_search` 也把调用热度作为排名平局裁决。
 - **变更上下文**(`src/change-context.ts`):把 Git hunk 映射到稳定符号,再在有限深度内追踪带来源标签的调用者、import 依赖、入口路径、影响范围和可能受影响的测试,避免返回整个仓库。
-- **任务感知上下文**(`src/context.ts`):确定性地把任务路由到已有的搜索、地图、调用图、变更上下文和测试信号,再按统一优先级去重并限制字符预算。
+- **ContextPack**(`src/context.ts`、`src/context-pack.ts`、`src/source-excerpts.ts`)：候选排序、临时读取源码证据、按文本/JSON 预算选择唯一 DTO，再渲染入选项。
 - **健康检查**(`src/health.ts`):对 import 图跑 Tarjan SCC 得到环依赖;孤儿模块检测列出既不被 import、也不 import 任何文件的含符号文件(排除入口与测试)。
 - **工作区解析**:每个工具解析会话 cwd(`agent.session.header.cwd`)并向上查找最近的 `.git`(有界——没有仓库标记的目录绝不会被索引)。
 - **项目上下文**(`src/repo-context.ts`):用真实规范路径区分各 worktree,最多保留四个上下文。每次工具调用扫描文件元数据并只重解析变化文件;watcher 会在有限 debounce 后刷新脏文件。
@@ -155,9 +196,8 @@ TypeScript、JavaScript、Python、Go、Rust、Java、C++、C(`.ts .tsx .mts .ct
 - 自动注入地图使用 DSH system prompt assembly 提供的当前会话上下文。没有 Agent 的 prompt assembly 会回退到 DSH 进程工作目录。新访问的项目第一次注入可能暂时为空,待索引完成后后续 assembly 会使用项目地图。
 - Watcher 只为工具实际访问的项目启动,并随插件卸载清理。设置 `externalWatch: false` 后,每次工具调用仍会扫描元数据以发现常规 mtime 变化。
 - 大型 monorepo 每次工具调用仍需要扫描目录元数据。文件解析是增量的,但扫描耗时取决于仓库规模和磁盘速度。
-- 当前已通过预览版 DSH API 的类型检查、包级生命周期模拟;真实 DSH Web 安装/启停仍是发布前验证项。
-- 局部变量也会被索引——召回优先于精确;`code_search` 的排名会压低它们。
-- 开发者预览版 harness:上游 harness/插件 API 大概率有破坏性变更。
+- 不索引函数局部变量；索引模块声明和类成员，parser/graph 不等同于 type checker。
+- current 源码读取会拒绝索引快照后发生变化、真实路径越出 root 或超过 1 MB 的文件；signature-only 和 gaps 标明缺失证据。Likely tests 是线索，不保证覆盖。
 
 ## 开发
 
@@ -182,8 +222,11 @@ node.exe scripts\fix-wsl-links.mjs C:\Users\you\.dsh\profiles\web   # dsh profil
 
 ## 反馈
 
-发现 bug,或者地图排名不合理?请[提 issue](https://github.com/lemonxiny55/dsh-code-index/issues)——真实使用报告(排名失准的仓库、想支持的语言)直接决定路线图。
+用过 dsh-code-index？欢迎告诉我哪些地方有帮助、哪里出错，或缺少了什么上下文。可以回复[DSH 官方插件介绍讨论](https://github.com/deepseek-ai/deepseek-harness/discussions/5623)；如果仓库允许创建 Issue，也可以使用[反馈 Issue 表单](https://github.com/lemonxiny55/dsh-code-index/issues/new?template=feedback.yml)。
+
+为了方便复现，请尽量说明仓库的大致规模和语言、执行的任务、预期上下文与 Agent 实际收到的内容，以及是否涉及项目切换、worktree 或外部文件修改。请勿粘贴私有源码、凭据或 API key。
 
 ## 许可证
 
 MIT。与 DeepSeek 无关;基于公开的 `dsh` 插件接口构建。
+