Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: apply hierarchy across the corpus

Browse Source
This commit is contained in:
Turtle
2026-08-04 00:54:19 +08:00
parent f07f8f15ed
commit dd8d446286
112 changed files with 705 additions and 1057 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
packages/core/README.md
View File

@@ -6,15 +6,13 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, and co
| Package | Role | ctx key |
|---|---|---|
| `scope/` | Scoped-context registration primitive (scope tags, scope-filtered dispatch) | (library — no ctx key) |
| `session/` | Event-sourced session log + in-memory store | `ctx.sessions` |
| `system-prompt/` | Prompt-section + tool-schema assembly registry | `ctx.systemPrompt` |
| `tools/` | Scoped tool registry + pre-policy, guards, around-dispatch, post-policy, and final-result observation | `ctx.tools` |
| `agent/` | Agent interface, live registry, process-local initiator scope, `agent/*` event vocabulary | `ctx.agents` |
| `agent-loop/` | Concrete plugin implementing the public `Agent` contract and owning the loop driver | `ctx.agentLoop` |
| [`scope/`](scope/README.md) | Scoped-context registration primitive | library — no ctx key |
| [`session/`](session/README.md) | Event-sourced session log and in-memory store | `ctx.sessions` |
| [`system-prompt/`](system-prompt/README.md) | Prompt and tool-schema assembly registry | `ctx.systemPrompt` |
| [`tools/`](tools/README.md) | Scoped tool registry and execution pipeline | `ctx.tools` |
| [`agent/`](agent/README.md) | Agent interface, registry, and event vocabulary | `ctx.agents` |
| [`agent-loop/`](agent-loop/README.md) | Default concrete agent driver | `ctx.agentLoop` |
`scope/` is the one non-service package here: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) the registries and the loop build per-agent scoping on — it sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle.
`scope` supplies the shared scoping primitive. `agent` owns the public seam, while `agent-loop` is its default implementation; extension plugins depend on the seam so the driver remains swappable.
`agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop. It runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent`, including when they need the initiating Agent, and never on `agent-loop` directly, so the loop stays swappable.
The default composition that wires this spine into a runnable agent lives in [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md): one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + fallback session titles + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + workspace-context + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. It sits in `examples/` — ready-to-run demo/reference bundles — not in `core/`: `core/` ships the swappable spine pieces, while a demo bundle picks one concrete composition of them and adds a front door.
Runnable compositions belong to [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md); this group owns only the swappable spine pieces.

18
packages/core/README.zh.md
View File

@@ -6,15 +6,13 @@
| 包 | 角色 | ctx 键 |
|---|---|---|
| `scope/` | 带作用域的上下文注册原语（作用域标签、按作用域筛选的分发） | （库，没有 ctx 键） |
| `session/` | 事件溯源会话日志与内存存储 | `ctx.sessions` |
| `system-prompt/` | 提示词段与工具 schema 组装注册表 | `ctx.systemPrompt` |
| `tools/` | 带作用域的工具注册表，以及前置策略、守卫、环绕分发、后置策略与最终结果观测 | `ctx.tools` |
| `agent/` | Agent 接口、实时注册表、进程本地发起方作用域、`agent/*` 事件词汇 | `ctx.agents` |
| `agent-loop/` | 实现公开 `Agent` 契约并拥有循环驱动器的具体插件 | `ctx.agentLoop` |
| [`scope/`](scope/README.md) | 带作用域的上下文注册原语 | 库，无 ctx 键 |
| [`session/`](session/README.md) | 事件溯源会话日志与内存存储 | `ctx.sessions` |
| [`system-prompt/`](system-prompt/README.md) | 提示词与工具 schema 组装注册表 | `ctx.systemPrompt` |
| [`tools/`](tools/README.md) | 带作用域的工具注册表与执行流水线 | `ctx.tools` |
| [`agent/`](agent/README.md) | Agent 接口、注册表与事件词汇 | `ctx.agents` |
| [`agent-loop/`](agent-loop/README.md) | 默认的具体 agent 驱动器 | `ctx.agentLoop` |
`scope/` 是此处唯一的非服务包：它是不含依赖的库（`createScope`/`scopeOf`/`scopeTarget`），注册表和循环基于它实现按 agent 分域。它在模块图中位于 `session/` 和 `system-prompt/` 之下，正是为了让二者可以消费它而不形成环。
`scope` 提供共享的作用域原语。`agent` 拥有公开 seam，`agent-loop` 则是其默认实现；扩展插件依赖 seam，使驱动器保持可替换。
`agent-loop` 是 `agent` seam 的唯一具体实现，位于此处是因为它就是 harness 的默认产品循环。它在 `ctx.agents.withInitiator()` 中运行每个驱动器。扩展插件依赖 `agent`，即使需要发起调用的 Agent 也是如此；它们绝不直接依赖 `agent-loop`，因此循环保持可替换。
将这条主干接成可运行 agent 的默认组合位于 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)：一个 bundle（组合包）插件，加载控制主干及所选默认能力（`timer` + `llm` + 会话 + 后备会话标题 + 系统提示词 + 工具 + agent + 不变式 + 本地 [skill（技能）系列](../skill/README.md) + `tool-bash` + 工作区上下文 + `agent-loop`），并将 `agent-loop` 的 `agents` 列表作为自身配置转发。它位于 `examples/`，即开箱可运行的演示／参考组合包，而不是 `core/`：`core/` 交付可替换的主干组件，演示组合包则选定其中一种具体组合并添加一个对外交互入口。
可运行组合属于 [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md)；本组只负责可替换的主干组件。