dsh-code-index 0.8.0 → 0.9.1

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to dsh-code-index are documented here.
 
+## 0.9.1 — Gitignore directory whitelist fix (2026-10-10)
+
+- Fix Gitignore directory whitelist rules (`!dir/`) silently excluding source trees: directory probes now retain their trailing slash in both the scanner and watcher. Thanks to @bbskye5008 for the detailed report and reproduction in [Issue #2](https://github.com/lemonxiny55/dsh-code-index/issues/2).
+- Apply nested `.gitignore` precedence consistently, while preserving Git's rule that files inside an ignored parent directory cannot be re-included. Add regressions for source/context retrieval, affected tests, and external add/change/delete freshness.
+- Verified on Node 22/24 and with a real DSH Desktop Agent using the packaged candidate. See `RELEASE_EVIDENCE_v0.9.1.md` for methods, results and publication status.
+
+## 0.9.0 — Edit-ready Context Packs (2026-10-05)
+
+- `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; Card replay/navigation remain unverified. No Card screenshot or benchmark claim is made.
+- Final DSH Desktop `0.2.0-rc.2` real Agent verification passed: default text and explicit pack calls, bounded source/reasons/provenance, related tests, change classification and external freshness. The npm package was published manually on 2026-10-05.
+
+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,68 @@
 
 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.
+
+v0.9.0 is published on npm and passed real Agent verification in DSH Desktop `0.2.0-rc.2`. 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. Install the published version into a Web profile:
+
+```sh
+npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add dsh-code-index@0.9.0
+npx @deepseek-ai/dsh@0.2.0-rc.2 web
+```
+
+For local development, run `pnpm install` and `pnpm build` at the repository root, then use `plugin --profile web add .`. See [Install](#install) for profile options.
+
+## 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
+
+**42 seconds in DSH Desktop: why did loading `' input '` produce `'INPUT'`?**
+
+![Actual DSH Desktop Agent calling code_context, with a bilingual task and explanation](assets/desktop-agent-v090.gif)
+
+One real `code_context` call returned `loadConfig` at `src/config.ts:1–3`, its callers, Git additions/modifications/deletions, and a likely test, with inclusion reasons and relationship provenance: **2347/5000 characters**. The Agent used that context to identify `.toUpperCase()` as the cause.
+
+This is **actual desktop footage recorded on 2026-10-08**, using the installed v0.9.0 plugin and a tiny demonstration repository. Only DSH is shown; waiting was cut and audio removed. No files were edited or tests run. The clip is not a latency measurement or a claim that a fix/tests succeeded. [MP4](assets/desktop-agent-v090.mp4) · [Recording notes and provenance](assets/desktop-agent-v090.md) · [Actual tool-card evidence](assets/desktop-agent-v090.evidence.json).
+
+The earlier [bilingual terminal replay](assets/agent-context-demo.md) remains available as a separate, clearly labeled replay of audited 2026-10-05 Agent records. It also shows external-edit freshness and a 500-character signature-only fallback.
+
+Try asking: **“Use code_context to locate a config-loading bug, show the relevant source and callers, and identify likely tests.”** Tell us what helped or what context was missing in the [DSH discussion](https://github.com/deepseek-ai/deepseek-harness/discussions/5623).
+
+The earlier [30-second local tool demo](assets/context-pack-demo.html) remains available and can be reproduced with `pnpm build`, then `node scripts/context-pack-demo.mjs`. Web Context Card remains deferred; Card replay and file navigation have not been verified.
+
+## Tools
 
 | Tool | Purpose |
 |---|---|
@@ -19,37 +76,28 @@ 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)
-npx @deepseek-ai/dsh plugin --profile web add dsh-code-index
+npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add dsh-code-index@0.9.0
 
 # or from a directory containing this checkout
-npx @deepseek-ai/dsh plugin --profile web add ./dsh-code-index
+npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add ./dsh-code-index
 ```
 
-Restart the Web UI (`npx @deepseek-ai/dsh web`) — startup logs confirm each tool:
+Restart the Web UI (`npx @deepseek-ai/dsh@0.2.0-rc.2 web`) — startup logs confirm each tool:
 
 ```
 [dsh-code-index] plugin loaded
@@ -72,61 +120,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 +182,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 +193,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 +220,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,68 @@
 
 [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 配置。
+
+v0.9.0 已发布到 npm，并通过 DSH Desktop `0.2.0-rc.2` 真实 Agent 验证。验证边界见[release evidence](RELEASE_EVIDENCE_v0.9.0.md)。
+
+## 本页导航
+
+- [🚀 快速开始](#快速开始)
+- [🧭 项目隔离与实时更新](#项目隔离与实时更新)
+- [👀 实际效果](#实际效果)
+- [🧰 工具一览](#工具一览)
+- [配置](#配置)
+- [支持的语言](#支持的语言)
+- [工作原理](#工作原理)
+- [已知限制](#已知限制)
+- [反馈](#反馈)
+
+## 快速开始
+
+需要 Node 22/24 与匹配的 DSH `0.2.0-rc.2` 宿主版本组。将已发布版本安装到 Web profile：
+
+```sh
+npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add dsh-code-index@0.9.0
+npx @deepseek-ai/dsh@0.2.0-rc.2 web
+```
+
+本地开发时，在仓库根目录运行 `pnpm install`、`pnpm build`，然后使用 `plugin --profile web add .`。其他 profile 选项见[安装说明](#安装)。
+
+## 项目隔离与实时更新
+
+```text
+打开仓库 A → 搜索到 A 的符号
+切换到仓库 B → 搜索到 B 的符号,不会混入 A
+从 DSH 外部修改文件 → 下一次查询看到变化
+切回 A → A 的上下文仍然独立
+```
+
+每个 Git worktree 都有独立索引和变更状态。插件会监听会话访问过的项目,并在工具调用时检查文件元数据,因此新增、修改和删除都会自动反映到后续查询,无需手动重建。
+
+## 实际效果
+
+**42 秒真实 DSH 桌面演示：加载 `' input '` 为什么变成了 `'INPUT'`？**
+
+![真实 DSH Desktop Agent 调用 code_context，含中英文任务与解释](assets/desktop-agent-v090.gif)
+
+一次真实 `code_context` 调用返回 `src/config.ts:1–3` 的 `loadConfig`、调用方、Git 增改删和相关测试线索，附入选理由与关系来源，共 **2347/5000 字符**。Agent 据此定位到改变大小写的 `.toUpperCase()`。
+
+这是 **2026-10-08 新录制的真实桌面画面**，使用已安装的 v0.9.0 与一个小演示仓库。只展示 DSH，剪去等待并移除音轨；没有修改文件或运行测试，不代表实际耗时，也不宣称修复或测试成功。[MP4 视频](assets/desktop-agent-v090.mp4) · [录制与来源说明](assets/desktop-agent-v090.md) · [实际工具卡片证据](assets/desktop-agent-v090.evidence.json)。
+
+先前的[中英终端回放](assets/agent-context-demo.md)继续保留，单独标明来自 2026-10-05 的真实 Agent 记录，补充展示外部编辑刷新及 500 字符下的签名降级。
+
+可以先试一句：**“用 code_context 定位一个配置加载 Bug，给出相关源码、调用者和可能受影响的测试。”** 欢迎在 [DSH Discussion](https://github.com/deepseek-ai/deepseek-harness/discussions/5623) 分享哪些上下文有帮助、哪些被漏掉。
+
+早期的 [30 秒本地工具演示](assets/context-pack-demo.html) 仍然保留，可用 `pnpm build` 后运行 `node scripts/context-pack-demo.mjs` 复现。Web Context Card 继续延期，Card replay 和文件跳转尚未验证。
+
+## 工具一览
 
 | 工具 | 用途 |
 |---|---|
@@ -16,37 +73,28 @@
 | `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(预编译)
-npx @deepseek-ai/dsh plugin --profile web add dsh-code-index
+npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add dsh-code-index@0.9.0
 
 # 或从包含本仓库检查副本的目录
-npx @deepseek-ai/dsh plugin --profile web add ./dsh-code-index
+npx @deepseek-ai/dsh@0.2.0-rc.2 plugin --profile web add ./dsh-code-index
 ```
 
-重启 Web UI(`npx @deepseek-ai/dsh web`)——启动日志会确认每个工具:
+重启 Web UI(`npx @deepseek-ai/dsh@0.2.0-rc.2 web`)——启动日志会确认每个工具:
 
 ```
 [dsh-code-index] plugin loaded
@@ -69,41 +117,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` 是 Agent 面对“代码任务”而不是单个符号时的高级入口。确定性的路由器识别修改、符号、架构、测试、探索和模糊任务,然后把已有能力合并、排序、去重并限制在字符预算内。只传 `task` 即可,也可以覆盖 `budgetChars`、`maxFiles`、`maxSymbols`。它不调用外部模型/API,推导关系的 `exact`、`import-scoped`、`name-only` provenance 会继续保留。
+`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 字符，不影响路由。
+
+默认 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 +179,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 +191,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 +217,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` 插件接口构建。
+