From 4f8ff004e6f000e6e0b85d788690f6fce1e7efca Mon Sep 17 00:00:00 2001 From: pku-xht Date: Wed, 19 Aug 2026 02:01:56 +0800 Subject: [PATCH] docs(i18n): point tutorial entries at index pages --- docs/user/develop/basic/config.i18n.yaml | 2 +- docs/user/develop/basic/config.md | 2 +- docs/user/develop/basic/publish.i18n.yaml | 2 +- docs/user/develop/basic/publish.md | 2 +- docs/user/develop/basic/tool.i18n.yaml | 2 +- docs/user/develop/basic/tool.md | 4 +-- docs/user/develop/framework/events.i18n.yaml | 2 +- docs/user/develop/framework/events.md | 2 +- docs/user/develop/framework/service.i18n.yaml | 2 +- docs/user/develop/framework/service.md | 2 +- docs/user/develop/practice/index.i18n.yaml | 2 +- docs/user/develop/practice/index.md | 2 +- docs/user/guide/index.i18n.yaml | 2 +- docs/user/guide/index.md | 2 +- scripts/project-doc-site.spec.ts | 31 +++++++++++++++++++ 15 files changed, 46 insertions(+), 15 deletions(-) diff --git a/docs/user/develop/basic/config.i18n.yaml b/docs/user/develop/basic/config.i18n.yaml index d0354a670f..67f04137b3 100644 --- a/docs/user/develop/basic/config.i18n.yaml +++ b/docs/user/develop/basic/config.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/user/develop/basic/config.md -config.md: 21ba39fd7de1795e9139aff3e2b11743eedd4833 +config.md: d935fc3f3b5b42c5b3fbd8d3b0d398a2608aead3 config.zh.md: 642a413950e2d8deb8591bc688968607604c050d diff --git a/docs/user/develop/basic/config.md b/docs/user/develop/basic/config.md index 21ba39fd7d..d935fc3f3b 100644 --- a/docs/user/develop/basic/config.md +++ b/docs/user/develop/basic/config.md @@ -102,5 +102,5 @@ A configuration edit hot-replaces the plugin: the framework unloads the old inst ## Next steps - [Package and install a plugin](./publish.md) — ship the plugin as an installable package -- [Plugins and lifecycle](../framework/) — understand the full plugin lifecycle +- [Plugins and lifecycle](../framework/index.md) — understand the full plugin lifecycle - [Services and dependencies](../framework/service.md) — provide a service to other plugins diff --git a/docs/user/develop/basic/publish.i18n.yaml b/docs/user/develop/basic/publish.i18n.yaml index bd80990141..e1443bc31f 100644 --- a/docs/user/develop/basic/publish.i18n.yaml +++ b/docs/user/develop/basic/publish.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/user/develop/basic/publish.md -publish.md: 9548fe2f8e4636dd160c79cd0d50f01f8bdfd3d1 +publish.md: 17f83e5448d5cfc65cd128c3fe1abbaa88925f77 publish.zh.md: 00b8885d6cbd39fa9899e110b1d31ef96175e127 diff --git a/docs/user/develop/basic/publish.md b/docs/user/develop/basic/publish.md index 9548fe2f8e..17f83e5448 100644 --- a/docs/user/develop/basic/publish.md +++ b/docs/user/develop/basic/publish.md @@ -179,5 +179,5 @@ If you would rather not ask users for the allowance, distribute built artifacts ## Next steps -- [Plugins and lifecycle](../framework/) — the full plugin lifecycle +- [Plugins and lifecycle](../framework/index.md) — the full plugin lifecycle - [CLI behavior reference](../../../../apps/cli/reference/README.md) — exact layer precedence, flags, and profile mechanics diff --git a/docs/user/develop/basic/tool.i18n.yaml b/docs/user/develop/basic/tool.i18n.yaml index 290d9b7417..99fdfe2139 100644 --- a/docs/user/develop/basic/tool.i18n.yaml +++ b/docs/user/develop/basic/tool.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/user/develop/basic/tool.md -tool.md: eb262d131a7f2b540827e86e56f8c0a28cb5f904 +tool.md: 24a82d277e626ba78760a0afb1c41e2a157eb8ee tool.zh.md: a07bef588f5a18093cf2eb1971b855bf40d1d0b6 diff --git a/docs/user/develop/basic/tool.md b/docs/user/develop/basic/tool.md index eb262d131a..24a82d277e 100644 --- a/docs/user/develop/basic/tool.md +++ b/docs/user/develop/basic/tool.md @@ -2,7 +2,7 @@ English | [中文](tool.zh.md) -This tutorial adds a `greet` tool to the Web UI. Complete [Your first plugin](./) first and keep its `scratch-plugin` directory. +This tutorial adds a `greet` tool to the Web UI. Complete [Your first plugin](./index.md) first and keep its `scratch-plugin` directory. ## Create the tool plugin @@ -49,4 +49,4 @@ Open `http://127.0.0.1:3080` and ask: `Use the greet tool to greet Ada.` The mod - [Plugin configuration](./config.md) — make the greeting configurable. - [Tool authoring reference](../../../cookbook/adding-a-tool.md) — look up nested schemas, canonical values, background work, policy hooks, Code Mode, and UI cards. -- [Capability layering](../practice/) — split a replaceable capability into Service Definition, Service Provider, and Consumer packages. +- [Capability layering](../practice/index.md) — split a replaceable capability into Service Definition, Service Provider, and Consumer packages. diff --git a/docs/user/develop/framework/events.i18n.yaml b/docs/user/develop/framework/events.i18n.yaml index 0c8665418f..d3ac77ddf3 100644 --- a/docs/user/develop/framework/events.i18n.yaml +++ b/docs/user/develop/framework/events.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/user/develop/framework/events.md -events.md: 1d9fe5c8f5068de6ad8b2abaa85cf67be35c8459 +events.md: 17ce5f6c4a70e406b5e3d9e5dd26182f62dc9868 events.zh.md: 6936a5ad6c51393d2fbcd5103d4e418ce010d569 diff --git a/docs/user/develop/framework/events.md b/docs/user/develop/framework/events.md index 1d9fe5c8f5..17ce5f6c4a 100644 --- a/docs/user/develop/framework/events.md +++ b/docs/user/develop/framework/events.md @@ -139,5 +139,5 @@ export function apply(ctx: Context) { ## Next steps -- [Capability layering](../practice/) — understand events within capability interfaces +- [Capability layering](../practice/index.md) — understand events within capability interfaces - [LLM adapters](../practice/llm-adapter.md) — implement a complete LLM backend diff --git a/docs/user/develop/framework/service.i18n.yaml b/docs/user/develop/framework/service.i18n.yaml index 0845e4578c..46097d8361 100644 --- a/docs/user/develop/framework/service.i18n.yaml +++ b/docs/user/develop/framework/service.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/user/develop/framework/service.md -service.md: 03f4e7dc4df934495a4b203066183753b621339e +service.md: 1bcfe2e7690d9f93b871500660e0fbe1e3439b3f service.zh.md: b275c3d200fb50b1fab0e762d0154477c7ca4447 diff --git a/docs/user/develop/framework/service.md b/docs/user/develop/framework/service.md index 03f4e7dc4d..1bcfe2e769 100644 --- a/docs/user/develop/framework/service.md +++ b/docs/user/develop/framework/service.md @@ -145,4 +145,4 @@ The repository generates the service names, public methods, and source locations ## Next steps - [Event system](./events.md) — communicate between plugins without tight coupling -- [Capability layering](../practice/) — use services as capability interfaces +- [Capability layering](../practice/index.md) — use services as capability interfaces diff --git a/docs/user/develop/practice/index.i18n.yaml b/docs/user/develop/practice/index.i18n.yaml index afee664f13..6f854ca172 100644 --- a/docs/user/develop/practice/index.i18n.yaml +++ b/docs/user/develop/practice/index.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/user/develop/practice/index.md -index.md: cc6bd7a234305f6fa193341f15354b40855f72e9 +index.md: f7e10e14b78da0b2eb922ca0cafd3151d412efd1 index.zh.md: 55ed3d3a93008f63a3e677de935c1de4be8872e5 diff --git a/docs/user/develop/practice/index.md b/docs/user/develop/practice/index.md index cc6bd7a234..f7e10e14b7 100644 --- a/docs/user/develop/practice/index.md +++ b/docs/user/develop/practice/index.md @@ -2,7 +2,7 @@ English | [中文](index.zh.md) -This page has two parts: a concept reference for the three-role capability pattern, followed by an advanced tutorial that builds one capability. Complete the [basic plugin path](../basic/) and [services tutorial](../framework/service.md) first. +This page has two parts: a concept reference for the three-role capability pattern, followed by an advanced tutorial that builds one capability. Complete the [basic plugin path](../basic/index.md) and [services tutorial](../framework/service.md) first. ## Concept reference diff --git a/docs/user/guide/index.i18n.yaml b/docs/user/guide/index.i18n.yaml index f27bd6fe24..d8805d32de 100644 --- a/docs/user/guide/index.i18n.yaml +++ b/docs/user/guide/index.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/user/guide/index.md -index.md: 2ae8847e3e04e131517e505bbc3c5f2c1047a45c +index.md: fb97f8cec837ecebc427f94ea5210b940d6fee75 index.zh.md: 6cbfce0b884aee39d26797d38c78b33e05b71c63 diff --git a/docs/user/guide/index.md b/docs/user/guide/index.md index 2ae8847e3e..fb97f8cec8 100644 --- a/docs/user/guide/index.md +++ b/docs/user/guide/index.md @@ -27,4 +27,4 @@ The agent can read and edit workspace files, run commands, delegate work, and ma - [Configure models](./providers.md) - [Use the Python SDK](./python-sdk.md) - [Use other CLI modes](../../../apps/cli/README.md) -- [Develop a plugin](../develop/basic/) +- [Develop a plugin](../develop/basic/index.md) diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts index f737392e05..200263bb5a 100644 --- a/scripts/project-doc-site.spec.ts +++ b/scripts/project-doc-site.spec.ts @@ -310,6 +310,37 @@ describe('docsPages locale routes', () => { } }) + it('projects the audited tutorial entry links from explicit locale index pages', () => { + const entries = [ + ['docs/user/develop/basic/config.md', '../framework/index.md'], + ['docs/user/develop/basic/publish.md', '../framework/index.md'], + ['docs/user/develop/basic/tool.md', './index.md'], + ['docs/user/develop/basic/tool.md', '../practice/index.md'], + ['docs/user/develop/framework/events.md', '../practice/index.md'], + ['docs/user/develop/framework/service.md', '../practice/index.md'], + ['docs/user/develop/practice/index.md', '../basic/index.md'], + ['docs/user/guide/index.md', '../develop/basic/index.md'], + ] as const + + for (const [englishSource, englishTarget] of entries) { + for (const locale of ['en', 'root'] as const) { + const source = locale === 'root' ? englishSource.replace(/\.md$/, '.zh.md') : englishSource + const target = locale === 'root' ? englishTarget.replace(/\.md$/, '.zh.md') : englishTarget + const page = docsPages.find(candidate => candidate.locale === locale && candidate.source === source) + expect(page, `${locale}:${source}`).toBeDefined() + expect(readFileSync(resolve(repositoryRoot, source), 'utf8')).toContain(`](${target})`) + expect(rewriteMarkdown(`[Entry](${target})\n`, { + locale, + sourcePath: source, + route: page!.route, + pages: docsPages, + repoRoot: repositoryRoot, + repositoryRef: 'abc123', + })).toBe(`[Entry](${englishTarget})\n`) + } + } + }) + it('indexes every subsystem page in both sides of the folder README', () => { const pages = globSync(join(repositoryRoot, 'docs/subsystems/*.md')) .map(page => basename(page))