Tianyi Cui
aa0ca6c836
core.md read as a type grab-bag: LLM wire vocabulary up front, the agent/loop story buried, and no correspondence to packages/core. It now opens on the packages/core control spine — the package-by-package loop map with a Page column into session/system-prompt/tools/scope — and keeps only what the spine group declares plus the repo-wide patterns: the Agent handle with its delivery/cancellation/interception contracts, the SessionEvent envelope, branded ids, the …Map pattern. The conversation vocabulary (Message/ContentBlock, the model request, adapters — 17 type-equiv blocks) moves to llm-streaming.md, which now declares packages/llm end-to-end; the duplicate ContentBlockMap paste near its seam section folds into the moved section, and the manifest, LINK_MAP, README table rows, website label (Core data structures → Core), and inbound anchors follow. Every packages/<group>/README pair is now a thin front door in one shape: a why-first intro (bash's seam-pattern-first paragraph rewritten as 'shell execution for the agent'), the package table, and a closing pointer to the owning docs/subsystems page — the bash-style table stays the load-bearing middle. Load-bearing trailing paragraphs relocate rather than vanish: the fs no-timeout rationale becomes a filesystem.md section (both languages), session's four sectioned tables merge into one 12-row table, examples' legacy-bin H2 collapses to a pointer at jsonrpc-demo's README, and design rationale that already lives in an Agent Note or subsystem page is now linked instead of restated. All 40 pair records re-recorded.
393 lines
15 KiB
TypeScript
393 lines
15 KiB
TypeScript
/**
|
|
* Canonical publication manifest for the documentation website.
|
|
*
|
|
* Markdown stays in its owning repository tier. This manifest maps each
|
|
* canonical source into matching route trees for both site locales; when a
|
|
* translation is absent, both routes intentionally project the available
|
|
* source instead of copying Markdown.
|
|
*/
|
|
|
|
/** Locale key used by the VitePress site. */
|
|
export type DocsLocale = 'root' | 'en'
|
|
|
|
/** Sidebar collection rendered for one locale and top-level module. */
|
|
type DocsSidebar =
|
|
| 'zh-guide'
|
|
| 'zh-develop'
|
|
| 'zh-reference'
|
|
| 'en-guide'
|
|
| 'en-develop'
|
|
| 'en-reference'
|
|
|
|
/** A page projected into the VitePress source tree. */
|
|
export interface DocsPage {
|
|
/** VitePress locale whose route tree owns this projection. */
|
|
locale: DocsLocale
|
|
/** Language of the canonical source currently projected at this route. */
|
|
contentLocale: 'zh-CN' | 'en-US'
|
|
/** Repository-relative canonical Markdown source. */
|
|
source: string
|
|
/** VitePress route, including the `.md` suffix. */
|
|
route: string
|
|
/** Navigation label shown in the sidebar. */
|
|
label: string
|
|
/** Sidebar collection that owns the page, or null for a locale home page. */
|
|
sidebar: DocsSidebar | null
|
|
/** Section label within the sidebar. */
|
|
section: string
|
|
/** Stable order within the section. */
|
|
order: number
|
|
/** Heading levels included in this page's VitePress outline. */
|
|
outline?: number | readonly [number, number] | 'deep' | false
|
|
/** Additional repository paths that resolve to this page. */
|
|
sourceAliases?: string[]
|
|
}
|
|
|
|
interface MirroredPage {
|
|
source: string | Record<DocsLocale, string>
|
|
route: string
|
|
contentLocale: DocsPage['contentLocale'] | Record<DocsLocale, DocsPage['contentLocale']>
|
|
label: Record<DocsLocale, string>
|
|
sidebar: Record<DocsLocale, DocsSidebar | null>
|
|
section: Record<DocsLocale, string>
|
|
order: number
|
|
outline?: DocsPage['outline']
|
|
sourceAliases?: string[] | Partial<Record<DocsLocale, string[]>>
|
|
}
|
|
|
|
type PairedPage = Omit<MirroredPage, 'source' | 'contentLocale' | 'sourceAliases'> & {
|
|
/** English side of a sibling `foo.md` / `foo.zh.md` pair. */
|
|
source: string
|
|
/** Language-neutral repository aliases, such as the directory of an index page. */
|
|
sourceAliases?: string[]
|
|
}
|
|
|
|
function localized<T>(value: T | Record<DocsLocale, T>, locale: DocsLocale): T {
|
|
return typeof value === 'object' && value !== null && !Array.isArray(value)
|
|
? (value as Record<DocsLocale, T>)[locale]
|
|
: value
|
|
}
|
|
|
|
function mirroredPages(pages: MirroredPage[]): DocsPage[] {
|
|
return pages.flatMap(page => (['root', 'en'] as const).map((locale) => {
|
|
const aliases = page.sourceAliases === undefined
|
|
? undefined
|
|
: Array.isArray(page.sourceAliases) ? page.sourceAliases : page.sourceAliases[locale]
|
|
return {
|
|
locale,
|
|
contentLocale: localized(page.contentLocale, locale),
|
|
source: localized(page.source, locale),
|
|
route: locale === 'root' ? page.route : `en/${page.route}`,
|
|
label: page.label[locale],
|
|
sidebar: page.sidebar[locale],
|
|
section: page.section[locale],
|
|
order: page.order,
|
|
...(page.outline === undefined ? {} : { outline: page.outline }),
|
|
...(aliases === undefined ? {} : { sourceAliases: aliases }),
|
|
}
|
|
}))
|
|
}
|
|
|
|
function pairedPages(pages: PairedPage[]): DocsPage[] {
|
|
return mirroredPages(pages.map((page) => {
|
|
const chineseSource = page.source.replace(/\.md$/, '.zh.md')
|
|
const sharedAliases = page.sourceAliases ?? []
|
|
return {
|
|
...page,
|
|
source: { root: chineseSource, en: page.source },
|
|
contentLocale: { root: 'zh-CN', en: 'en-US' },
|
|
sourceAliases: {
|
|
root: [...sharedAliases, page.source],
|
|
en: [...sharedAliases, chineseSource],
|
|
},
|
|
}
|
|
}))
|
|
}
|
|
|
|
const homeAndGuide = pairedPages([
|
|
{
|
|
source: 'docs/user/index.md',
|
|
route: 'index.md',
|
|
label: { root: 'DeepSeek Harness', en: 'DeepSeek Harness' },
|
|
sidebar: { root: null, en: null },
|
|
section: { root: '首页', en: 'Home' },
|
|
order: 0,
|
|
},
|
|
{
|
|
source: 'docs/user/guide/index.md',
|
|
route: 'guide/index.md',
|
|
label: { root: '介绍', en: 'Introduction' },
|
|
sidebar: { root: 'zh-guide', en: 'en-guide' },
|
|
section: { root: '入门', en: 'Guide' },
|
|
order: 1,
|
|
sourceAliases: ['docs/user/guide'],
|
|
},
|
|
{
|
|
source: 'docs/user/guide/quickstart.md',
|
|
route: 'guide/quickstart.md',
|
|
label: { root: '快速开始', en: 'Quick start' },
|
|
sidebar: { root: 'zh-guide', en: 'en-guide' },
|
|
section: { root: '入门', en: 'Guide' },
|
|
order: 2,
|
|
},
|
|
{
|
|
source: 'docs/user/guide/providers.md',
|
|
route: 'guide/providers.md',
|
|
label: { root: '配置模型', en: 'Configure models' },
|
|
sidebar: { root: 'zh-guide', en: 'en-guide' },
|
|
section: { root: '入门', en: 'Guide' },
|
|
order: 3,
|
|
},
|
|
{
|
|
source: 'docs/user/guide/config.md',
|
|
route: 'guide/config.md',
|
|
label: { root: '配置文件', en: 'Configuration' },
|
|
sidebar: { root: 'zh-guide', en: 'en-guide' },
|
|
section: { root: '入门', en: 'Guide' },
|
|
order: 4,
|
|
},
|
|
])
|
|
|
|
const develop = pairedPages([
|
|
{
|
|
source: 'docs/user/develop/basic/index.md',
|
|
route: 'develop/basic/index.md',
|
|
label: { root: '第一个插件', en: 'First plugin' },
|
|
sidebar: { root: 'zh-develop', en: 'en-develop' },
|
|
section: { root: '基础', en: 'Basics' },
|
|
order: 1,
|
|
sourceAliases: ['docs/user/develop/basic'],
|
|
},
|
|
{
|
|
source: 'docs/user/develop/basic/tool.md',
|
|
route: 'develop/basic/tool.md',
|
|
label: { root: '开发一个 Tool', en: 'Build a tool' },
|
|
sidebar: { root: 'zh-develop', en: 'en-develop' },
|
|
section: { root: '基础', en: 'Basics' },
|
|
order: 2,
|
|
},
|
|
{
|
|
source: 'docs/user/develop/basic/config.md',
|
|
route: 'develop/basic/config.md',
|
|
label: { root: '插件配置', en: 'Plugin configuration' },
|
|
sidebar: { root: 'zh-develop', en: 'en-develop' },
|
|
section: { root: '基础', en: 'Basics' },
|
|
order: 3,
|
|
},
|
|
{
|
|
source: 'docs/user/develop/basic/publish.md',
|
|
route: 'develop/basic/publish.md',
|
|
label: { root: '打包与安装插件', en: 'Package and install' },
|
|
sidebar: { root: 'zh-develop', en: 'en-develop' },
|
|
section: { root: '基础', en: 'Basics' },
|
|
order: 4,
|
|
},
|
|
{
|
|
source: 'docs/user/develop/framework/index.md',
|
|
route: 'develop/framework/index.md',
|
|
label: { root: '插件与生命周期', en: 'Plugin lifecycle' },
|
|
sidebar: { root: 'zh-develop', en: 'en-develop' },
|
|
section: { root: '框架能力', en: 'Framework' },
|
|
order: 1,
|
|
sourceAliases: ['docs/user/develop/framework'],
|
|
},
|
|
{
|
|
source: 'docs/user/develop/framework/service.md',
|
|
route: 'develop/framework/service.md',
|
|
label: { root: '服务与依赖', en: 'Services and dependencies' },
|
|
sidebar: { root: 'zh-develop', en: 'en-develop' },
|
|
section: { root: '框架能力', en: 'Framework' },
|
|
order: 2,
|
|
},
|
|
{
|
|
source: 'docs/user/develop/framework/events.md',
|
|
route: 'develop/framework/events.md',
|
|
label: { root: '事件系统', en: 'Event system' },
|
|
sidebar: { root: 'zh-develop', en: 'en-develop' },
|
|
section: { root: '框架能力', en: 'Framework' },
|
|
order: 3,
|
|
},
|
|
{
|
|
source: 'docs/user/develop/practice/index.md',
|
|
route: 'develop/practice/index.md',
|
|
label: { root: '能力的三层拆分', en: 'Capability layering' },
|
|
sidebar: { root: 'zh-develop', en: 'en-develop' },
|
|
section: { root: '实战', en: 'Practice' },
|
|
order: 1,
|
|
sourceAliases: ['docs/user/develop/practice'],
|
|
},
|
|
{
|
|
source: 'docs/user/develop/practice/llm-adapter.md',
|
|
route: 'develop/practice/llm-adapter.md',
|
|
label: { root: 'LLM 适配器', en: 'LLM adapter' },
|
|
sidebar: { root: 'zh-develop', en: 'en-develop' },
|
|
section: { root: '实战', en: 'Practice' },
|
|
order: 2,
|
|
},
|
|
])
|
|
|
|
const cordisTutorial = mirroredPages(([
|
|
['index.md', 'Cordis 教程', 'Cordis tutorial'],
|
|
['01-first-plugin.md', '1. 第一个插件', '1. Your first plugin'],
|
|
['02-lifecycle-and-effects.md', '2. 生命周期与副作用', '2. Lifecycle and effects'],
|
|
['03-services.md', '3. 服务', '3. Services'],
|
|
['04-events.md', '4. 事件', '4. Events'],
|
|
['05-config.md', '5. 配置', '5. Configuration'],
|
|
['06-composition-and-hmr.md', '6. 组合与热重载', '6. Composition and HMR'],
|
|
['07-into-the-harness.md', '7. 进入 Harness', '7. Into the harness'],
|
|
] as const).map(([file, rootLabel, enLabel], order): MirroredPage => ({
|
|
source: `docs/cordis-tutorial/${file}`,
|
|
route: `develop/cordis-tutorial/${file}`,
|
|
contentLocale: 'en-US',
|
|
label: { root: rootLabel, en: enLabel },
|
|
sidebar: { root: 'zh-develop', en: 'en-develop' },
|
|
section: { root: 'Cordis 教程', en: 'Cordis tutorial' },
|
|
order,
|
|
...(file === 'index.md' ? { sourceAliases: ['docs/cordis-tutorial'] } : {}),
|
|
})))
|
|
|
|
const cordisPrimerReference = pairedPages([
|
|
{
|
|
source: 'docs/cordis-primer.md',
|
|
route: 'reference/cordis-primer.md',
|
|
label: { root: 'Cordis 入门', en: 'Cordis primer' },
|
|
sidebar: { root: 'zh-reference', en: 'en-reference' },
|
|
section: { root: '概念', en: 'Concepts' },
|
|
order: 1,
|
|
},
|
|
])
|
|
|
|
const subsystemsReference = pairedPages(([
|
|
['README.md', '子系统', 'Subsystems', 0],
|
|
['core.md', '核心', 'Core', 1],
|
|
['scope.md', '作用域', 'Scopes', 2],
|
|
['session.md', '会话', 'Sessions', 3],
|
|
['session-query.md', '会话查询', 'Session query', 4],
|
|
['session-reference.md', '会话引用', 'Session references', 5],
|
|
['session-title.md', '会话标题', 'Session titles', 6],
|
|
['settings.md', '用户设置', 'User settings', 7],
|
|
['credentials.md', '用户凭据', 'User credentials', 8],
|
|
['system-prompt.md', '系统提示词', 'System prompts', 9],
|
|
['tools.md', '工具', 'Tools', 10],
|
|
['llm-streaming.md', 'LLM 流式响应', 'LLM streaming', 11],
|
|
['token-meter.md', 'Token 计量', 'Token metering', 12],
|
|
['bash.md', 'Bash 执行', 'Bash execution', 13],
|
|
['subprocess.md', '子进程', 'Subprocesses', 14],
|
|
['tasks.md', '后台任务', 'Background tasks', 15],
|
|
['filesystem.md', '文件系统', 'Filesystem', 16],
|
|
['lsp.md', 'LSP 导航', 'LSP navigation', 17],
|
|
['code-runtime.md', '代码运行时', 'Code runtime', 18],
|
|
['compaction.md', '上下文压缩', 'Compaction', 19],
|
|
['subagent.md', '子代理', 'Subagents', 20],
|
|
['workflow.md', '工作流', 'Workflows', 21],
|
|
['skills.md', '技能', 'Skills', 22],
|
|
['approval.md', '审批', 'Approvals', 23],
|
|
['permission.md', '权限预设', 'Permission presets', 24],
|
|
['plan.md', '计划模式', 'Plan mode', 25],
|
|
['user-interaction.md', '用户交互', 'User interaction', 26],
|
|
['sandbox.md', '沙箱', 'Sandboxing', 27],
|
|
['web.md', 'Web 访问', 'Web access', 28],
|
|
['spill.md', 'Spill 存储', 'Spill storage', 29],
|
|
['persistence.md', '会话持久化', 'Session persistence', 30],
|
|
['storage.md', '存储', 'Storage', 31],
|
|
['workspace.md', '工作区', 'Workspaces', 32],
|
|
['http-server.md', 'HTTP 服务器', 'HTTP server', 33],
|
|
['client-modules.md', '客户端模块', 'Client modules', 34],
|
|
['tui.md', 'TUI 扩展', 'TUI extensions', 35],
|
|
['invariants.md', '运行时不变式', 'Runtime invariants', 36],
|
|
['session-projection.md', '会话投影', 'Session projections', 37],
|
|
['telemetry.md', '遥测', 'Telemetry', 38],
|
|
] as const).map(([file, rootLabel, enLabel, order]): PairedPage => ({
|
|
source: `docs/subsystems/${file}`,
|
|
route: file === 'README.md' ? 'reference/subsystems/index.md' : `reference/subsystems/${file}`,
|
|
label: { root: rootLabel, en: enLabel },
|
|
sidebar: { root: 'zh-reference', en: 'en-reference' },
|
|
section: { root: '子系统', en: 'Subsystems' },
|
|
order,
|
|
...(file === 'README.md' ? { sourceAliases: ['docs/subsystems'] } : {}),
|
|
})))
|
|
|
|
const reference = mirroredPages([
|
|
...([
|
|
['docs/architecture.md', 'reference/index.md', '架构', 'Architecture', 0],
|
|
['docs/capability-seams.md', 'reference/capability-seams.md', '能力服务', 'Capability services', 2],
|
|
['docs/agent-lifecycle.md', 'reference/agent-lifecycle.md', 'Agent 生命周期', 'Agent lifecycle', 3],
|
|
['docs/tool-execution-pipeline.md', 'reference/tool-execution-pipeline.md', 'Tool 执行', 'Tool execution', 4],
|
|
] as const).map(([source, route, rootLabel, enLabel, order]): MirroredPage => ({
|
|
source,
|
|
route,
|
|
contentLocale: 'en-US',
|
|
label: { root: rootLabel, en: enLabel },
|
|
sidebar: { root: 'zh-reference', en: 'en-reference' },
|
|
section: { root: '概念', en: 'Concepts' },
|
|
order,
|
|
})),
|
|
...([
|
|
['docs/config-catalog.md', 'reference/config-catalog.md', '插件配置', 'Plugin configuration'],
|
|
['docs/tool-catalog.md', 'reference/tool-catalog.md', 'Tool Schema', 'Tool schemas'],
|
|
['docs/persistence-catalog.md', 'reference/persistence-catalog.md', '持久化事件', 'Persistence events', 'deep'],
|
|
] as const).map(([source, route, rootLabel, enLabel, outline], order): MirroredPage => ({
|
|
source,
|
|
route,
|
|
contentLocale: 'en-US',
|
|
label: { root: rootLabel, en: enLabel },
|
|
sidebar: { root: 'zh-reference', en: 'en-reference' },
|
|
section: { root: '生成参考', en: 'Generated reference' },
|
|
order,
|
|
...(outline === undefined ? {} : { outline }),
|
|
})),
|
|
...([
|
|
['context.md', 'Context', 'Context'],
|
|
['events.md', 'Events', 'Events'],
|
|
['fiber.md', 'Fiber', 'Fiber'],
|
|
['registry.md', 'Plugin Registry', 'Plugin Registry'],
|
|
['service.md', 'Service', 'Service'],
|
|
['inherited.md', '继承接口面', 'Inherited surface'],
|
|
] as const).map(([file, rootLabel, enLabel], order): MirroredPage => ({
|
|
source: `docs/cordis-api/${file}`,
|
|
route: `reference/cordis-api/${file}`,
|
|
contentLocale: 'en-US',
|
|
label: { root: rootLabel, en: enLabel },
|
|
sidebar: { root: 'zh-reference', en: 'en-reference' },
|
|
section: { root: 'Cordis API', en: 'Cordis Core API' },
|
|
order,
|
|
})),
|
|
...([
|
|
['goal.md', '目标', 'Goals', 14],
|
|
['pty.md', 'PTY 会话', 'PTY sessions', 26],
|
|
['commands.md', '命令', 'Human commands', 38],
|
|
] as const).map(([file, rootLabel, enLabel, order]): MirroredPage => ({
|
|
source: `docs/subsystems/${file}`,
|
|
route: `reference/subsystems/${file}`,
|
|
contentLocale: 'en-US',
|
|
label: { root: rootLabel, en: enLabel },
|
|
sidebar: { root: 'zh-reference', en: 'en-reference' },
|
|
section: { root: '子系统', en: 'Subsystems' },
|
|
order,
|
|
})),
|
|
...([
|
|
['adding-a-package.md', '新增 Package', 'Adding a package'],
|
|
['adding-a-tool.md', '新增 Tool', 'Adding a tool'],
|
|
['adding-an-llm-adapter.md', '新增 LLM Adapter', 'Adding an LLM adapter'],
|
|
['extension-cookbook.md', '扩展模式', 'Extension patterns'],
|
|
] as const).map(([file, rootLabel, enLabel], order): MirroredPage => ({
|
|
source: `docs/cookbook/${file}`,
|
|
route: `reference/cookbook/${file}`,
|
|
contentLocale: 'en-US',
|
|
label: { root: rootLabel, en: enLabel },
|
|
sidebar: { root: 'zh-reference', en: 'en-reference' },
|
|
section: { root: '开发手册', en: 'Cookbook' },
|
|
order,
|
|
})),
|
|
])
|
|
|
|
/** Every canonical page published by the documentation website. */
|
|
export const docsPages: DocsPage[] = [
|
|
...homeAndGuide,
|
|
...develop,
|
|
...cordisTutorial,
|
|
...cordisPrimerReference,
|
|
...subsystemsReference,
|
|
...reference,
|
|
]
|