diff --git a/.github/actions/setup-node-pnpm/action.yml b/.github/actions/setup-node-pnpm/action.yml index 2a6fd8ad..52750864 100644 --- a/.github/actions/setup-node-pnpm/action.yml +++ b/.github/actions/setup-node-pnpm/action.yml @@ -27,7 +27,7 @@ runs: using: composite steps: - name: Setup pnpm - uses: pnpm/action-setup@v4 + uses: pnpm/action-setup@v5 with: version: ${{ inputs.pnpm-version }} diff --git a/doc/components/package-manager-tabs.tsx b/doc/components/package-manager-tabs.tsx index bbaa4793..eafe30db 100644 --- a/doc/components/package-manager-tabs.tsx +++ b/doc/components/package-manager-tabs.tsx @@ -85,7 +85,7 @@ export function PackageManagerTabs({ > {tab.label} {tab.id === recommendedManager - ? 推荐 + ? Recommended : null} ) diff --git a/doc/content/_meta.ts b/doc/content/_meta.ts index 1ea000a5..88faf40d 100644 --- a/doc/content/_meta.ts +++ b/doc/content/_meta.ts @@ -1,9 +1,9 @@ export default { 'index': { - title: '文档总览' + title: 'Overview' }, 'quick-guide': { - title: '快速指引' + title: 'Quick Guide' }, 'cli': { title: 'CLI' @@ -18,9 +18,9 @@ export default { title: 'GUI' }, 'technical-details': { - title: '技术细节' + title: 'Technical Details' }, 'design-rationale': { - title: '设计初衷' + title: 'Design Rationale' } } diff --git a/doc/content/cli/_meta.ts b/doc/content/cli/_meta.ts index bc38a43f..9d2c4689 100644 --- a/doc/content/cli/_meta.ts +++ b/doc/content/cli/_meta.ts @@ -1,17 +1,17 @@ export default { - 'index': '概览', - 'install': '安装与前提', - 'workspace-setup': '项目与 aindex', - 'first-sync': '第一次同步', - 'migration': '从旧文档迁移', - 'cli-commands': 'CLI 命令', - 'dry-run-and-clean': 'dry-run 与 clean', + 'index': 'Overview', + 'install': 'Installation and Requirements', + 'workspace-setup': 'Workspace and aindex', + 'first-sync': 'First Sync', + 'migration': 'Migrating from Older Docs', + 'cli-commands': 'CLI Commands', + 'dry-run-and-clean': 'dry-run and clean', 'plugin-config': 'plugin.config.ts', 'schema': 'JSON Schema', - 'output-scopes': '输出范围', + 'output-scopes': 'Output Scopes', 'frontmatter': 'Front Matter', - 'cleanup-protection': '清理保护', - 'supported-outputs': '支持的输出目标', - 'troubleshooting': '排障', - 'upgrade-notes': '升级说明' + 'cleanup-protection': 'Cleanup Protection', + 'supported-outputs': 'Supported Outputs', + 'troubleshooting': 'Troubleshooting', + 'upgrade-notes': 'Upgrade Notes' } diff --git a/doc/content/cli/cleanup-protection.mdx b/doc/content/cli/cleanup-protection.mdx index e73e23c0..8f9b53b2 100644 --- a/doc/content/cli/cleanup-protection.mdx +++ b/doc/content/cli/cleanup-protection.mdx @@ -1,41 +1,41 @@ --- -title: 清理保护 -description: 说明 cleanupProtection 规则如何避免 clean 命令误删不该删除的内容。 -sidebarTitle: 清理保护 +title: Cleanup Protection +description: Explains how cleanupProtection rules keep the clean command from deleting files that should not be removed. +sidebarTitle: Cleanup Protection status: stable --- -# 清理保护 +# Cleanup Protection -`clean` 不是无脑删文件，所以 `cleanupProtection` 也不是可有可无的附属字段。 +`clean` is not a brainless file-deletion command, so `cleanupProtection` is not an optional afterthought. -## 规则结构 +## Rule Structure -每条保护规则支持这些字段： +Each protection rule supports these fields: -| 字段 | 必填 | 说明 | +| Field | Required | Description | | --- | --- | --- | -| `path` | 是 | 目标路径或 glob | -| `protectionMode` | 是 | `direct` 或 `recursive` | -| `matcher` | 否 | `path` 或 `glob` | -| `reason` | 否 | 写明这条保护存在的原因 | +| `path` | Yes | Target path or glob | +| `protectionMode` | Yes | `direct` or `recursive` | +| `matcher` | No | `path` or `glob` | +| `reason` | No | Why this protection rule exists | -## 语义 +## Semantics -- `direct`：只保护这一个目标。 -- `recursive`：保护这一路径下的整棵子树。 +- `direct`: protect only this exact target. +- `recursive`: protect the entire subtree under this path. -## 什么时候必须配 +## When You Must Configure It -如果你的输出目录旁边混放了： +If your output directories are mixed with: -- 手写文件 -- 其他工具生成但不属于 tnmsc 的文件 -- 临时人工补丁 +- hand-written files +- files generated by other tools that are not owned by tnmsc +- temporary manual patches -那么在启用 `clean` 前最好先加保护规则，否则你迟早会把不该删的内容一起带走。 +then add protection rules before enabling `clean`, or sooner or later you will delete things that should have stayed. -## 推荐写法 +## Recommended Shape ```json { @@ -45,7 +45,7 @@ status: stable "path": ".cursor/local-notes", "protectionMode": "recursive", "matcher": "path", - "reason": "人工维护，不属于 tnmsc 输出" + "reason": "Maintained manually and not owned by tnmsc outputs" } ] } diff --git a/doc/content/cli/cli-commands.mdx b/doc/content/cli/cli-commands.mdx index 3731fb94..707b6939 100644 --- a/doc/content/cli/cli-commands.mdx +++ b/doc/content/cli/cli-commands.mdx @@ -1,34 +1,34 @@ --- -title: CLI 命令 -description: 基于当前 tnmsc --help 输出整理的命令与行为说明。 -sidebarTitle: CLI 命令 +title: CLI Commands +description: Summarizes the commands and behavior currently exposed by tnmsc --help. +sidebarTitle: CLI Commands status: stable --- -# CLI 命令 +# CLI Commands -当前 `tnmsc --help` 暴露的命令是： +The commands currently exposed by `tnmsc --help` are: -| 命令 | 说明 | +| Command | Description | | --- | --- | -| `tnmsc` | 执行默认同步管线 | -| `tnmsc help` | 查看帮助 | -| `tnmsc version` | 查看版本 | -| `tnmsc init` | 已废弃，不再初始化 aindex | -| `tnmsc dry-run` | 预览会写出的文件 | -| `tnmsc clean` | 删除已生成的输出文件，并继续清理 project 源码树中的空目录 | -| `tnmsc clean --dry-run` | 预览会清理什么，包括后续会被回收的空目录 | -| `tnmsc config key=value` | 修改全局配置 | +| `tnmsc` | Run the default sync pipeline | +| `tnmsc help` | Show help | +| `tnmsc version` | Show the version | +| `tnmsc init` | Deprecated and no longer initializes aindex | +| `tnmsc dry-run` | Preview the files that would be written | +| `tnmsc clean` | Delete generated outputs and continue cleaning empty directories from the project source tree | +| `tnmsc clean --dry-run` | Preview what would be cleaned, including empty directories that would be swept afterward | +| `tnmsc config key=value` | Change global config | -## 关键结论 +## Key Takeaways -### `init` 已经不应该出现在新流程里 +### `init` Should No Longer Appear in New Workflows -当前实现明确把它视为 deprecated，因此新文档不会再把它写成推荐入口。 +The current implementation treats it as deprecated, so new docs no longer present it as a recommended entrypoint. -### `config` 只能改一组白名单键 +### `config` Can Only Change a Whitelisted Set of Keys -当前 `ConfigCommand` 允许的键包括： +The current `ConfigCommand` allows these keys: - `workspaceDir` - `aindex.skills.src/dist` @@ -42,17 +42,17 @@ status: stable - `aindex.arch.src/dist` - `logLevel` -### `logLevel` 也有严格枚举 +### `logLevel` Is Also Strictly Enumerated -只能是： +It can only be: ```text trace / debug / info / warn / error ``` -## 推荐操作习惯 +## Recommended Habits -1. 新环境先 `tnmsc help` -2. 写出前先 `tnmsc dry-run` -3. 清理前先 `tnmsc clean --dry-run` -4. 真要改全局配置时，用 `tnmsc config`，不要手写出一份和 Schema 漂移的 JSON +1. Run `tnmsc help` first in a new environment. +2. Run `tnmsc dry-run` before writing outputs. +3. Run `tnmsc clean --dry-run` before cleanup. +4. If you really need to change global config, use `tnmsc config` instead of hand-editing JSON that can drift from the schema. diff --git a/doc/content/cli/dry-run-and-clean.mdx b/doc/content/cli/dry-run-and-clean.mdx index 66e4ddb6..31b9a888 100644 --- a/doc/content/cli/dry-run-and-clean.mdx +++ b/doc/content/cli/dry-run-and-clean.mdx @@ -1,41 +1,41 @@ --- -title: dry-run 与 clean -description: 说明 tnmsc 如何先预览输出，再执行清理，并配合 cleanupProtection 控制风险。 -sidebarTitle: dry-run 与 clean +title: dry-run and clean +description: Explains how tnmsc previews outputs, then performs cleanup, with cleanupProtection used to control risk. +sidebarTitle: dry-run and clean status: stable --- -# dry-run 与 clean +# dry-run and clean -## `dry-run` 的职责 +## What `dry-run` Does -`tnmsc dry-run` 用来预览当前执行会写出哪些文件与目录。它适合在这些场景先跑一遍： +`tnmsc dry-run` previews the files and directories that the current execution would write. It is especially useful in these situations: -- 第一次接入某个项目 -- 刚修改过 `plugin.config.ts` -- 刚改过 [输出范围](/docs/cli/output-scopes) -- 准备验证某次批量源内容变更的影响 +- When integrating a project for the first time +- Right after changing `plugin.config.ts` +- Right after changing [Output Scopes](/docs/cli/output-scopes) +- Before validating the impact of a large source-content change -## `clean` 的职责 +## What `clean` Does -`tnmsc clean` 用来清除已生成的输出文件。它不是“无差别删目录”，而是依据当前输出模型和清理保护规则执行。 +`tnmsc clean` removes generated output files. It is not a blind directory deletion command. It follows the current output model and cleanup-protection rules. -在完成常规 cleanup 之后，`tnmsc clean` 还会继续扫描当前 project 的源码树，把剩余的空目录一并清掉。这个 empty-dir sweep 会明确跳过 Git 内部目录，以及依赖、构建产物、缓存一类目录树。 +After normal cleanup finishes, `tnmsc clean` also scans the current project source tree and removes remaining empty directories. That empty-dir sweep explicitly skips Git internals as well as dependency, build-output, and cache directory trees. -在真正执行前，优先用： +Before running it for real, prefer: ```sh tnmsc clean --dry-run ``` -`--dry-run` 也会把这些后续会被清掉的空目录一起展示出来。 +`--dry-run` will also show the empty directories that would be removed afterward. -## 风险边界 +## Risk Boundary -如果输出目录里混有人工文件或其他工具产物，必须先看 [清理保护](/docs/cli/cleanup-protection)。没有保护规则时，`clean` 的风险会显著上升。 +If your output directories also contain hand-written files or outputs from other tools, read [Cleanup Protection](/docs/cli/cleanup-protection) first. Without protection rules, the risk of `clean` rises sharply. -## 推荐习惯 +## Recommended Habits -1. 改配置或换项目时先 `dry-run` -2. 真要清理时先 `clean --dry-run` -3. 出现异常时再结合 [排障](/docs/cli/troubleshooting) 定位 +1. Run `dry-run` first when you change config or switch projects. +2. Run `clean --dry-run` first when you really intend to clean. +3. If something looks wrong, continue with [Troubleshooting](/docs/cli/troubleshooting). diff --git a/doc/content/cli/first-sync.mdx b/doc/content/cli/first-sync.mdx index 1aedf1a7..7a996b67 100644 --- a/doc/content/cli/first-sync.mdx +++ b/doc/content/cli/first-sync.mdx @@ -1,19 +1,19 @@ --- -title: 第一次同步 -description: 按最短路径完成 tnmsc help、dry-run、真实同步与结果核对。 -sidebarTitle: 第一次同步 +title: First Sync +description: Walk through tnmsc help, dry-run, the real sync run, and result verification in the shortest path. +sidebarTitle: First Sync status: stable --- -# 第一次同步 +# First Sync -## 推荐顺序 +## Recommended Order -1. 先运行 `tnmsc help`，确认你面对的是当前命令集。 -2. 再运行 `tnmsc dry-run`，确认会写出哪些文件。 -3. 确认范围无误后，再执行默认同步管线。 +1. Run `tnmsc help` first to confirm that you are looking at the current command set. +2. Run `tnmsc dry-run` next to see which files would be written. +3. Only after confirming the scope should you run the default sync pipeline. -## 最短流程 +## Shortest Flow ```sh tnmsc help @@ -21,14 +21,14 @@ tnmsc dry-run tnmsc ``` -## 为什么不能直接跳过 `dry-run` +## Why You Should Not Skip `dry-run` -因为当前系统不仅会写文件，还会根据配置处理清理边界。第一次接入某个项目时，先看预览比事后回收误写和误删要便宜得多。 +The current system does more than write files. It also applies cleanup boundaries based on configuration. On a first integration, checking the preview is much cheaper than recovering from accidental writes or accidental deletions afterward. -如果你不确定清理风险，先补读 [dry-run 与 clean](/docs/cli/dry-run-and-clean) 和 [清理保护](/docs/cli/cleanup-protection)。 +If you are unsure about cleanup risk, read [dry-run and clean](/docs/cli/dry-run-and-clean) and [Cleanup Protection](/docs/cli/cleanup-protection) first. -## 同步后应该核对什么 +## What to Verify After Sync -- 目标工具是不是出现在 [支持的输出目标](/docs/cli/supported-outputs) 范围内 -- 真实写入范围是否符合 [输出范围](/docs/cli/output-scopes) -- 某些字段行为是否与 [JSON Schema](/docs/cli/schema) 一致 +- Whether the target tool appears in [Supported Outputs](/docs/cli/supported-outputs) +- Whether the actual write scope matches [Output Scopes](/docs/cli/output-scopes) +- Whether field behavior matches the [JSON Schema](/docs/cli/schema) diff --git a/doc/content/cli/frontmatter.mdx b/doc/content/cli/frontmatter.mdx index be68060c..a7a07760 100644 --- a/doc/content/cli/frontmatter.mdx +++ b/doc/content/cli/frontmatter.mdx @@ -1,30 +1,30 @@ --- title: Front Matter -description: 说明当前系统中配置 frontMatter 选项与内容 frontmatter 的不同层次。 +description: Explains the difference between the frontMatter config option and content frontmatter in the current system. sidebarTitle: Front Matter status: stable --- # Front Matter -这里要先分清两层 front matter。 +Start by separating two different layers of front matter. -## 1. 文档页自己的 frontmatter +## 1. A Docs Page's Own Frontmatter -这套文档站的每篇 MDX 页面当前要求至少包含： +Each MDX page in this docs site currently requires at least: - `title` - `description` -可选字段包括： +Optional fields include: - `sidebarTitle` - `status` - `keywords` -## 2. 同步系统的 `frontMatter` 配置 +## 2. The Sync System's `frontMatter` Config -Schema 与 `config.ts` 当前公开的配置项只有： +The only public config field in the schema and `config.ts` right now is: ```json { @@ -34,24 +34,24 @@ Schema 与 `config.ts` 当前公开的配置项只有： } ``` -它的作用不是描述页面本身，而是控制输出时 front matter 之后是否保留空行。 +Its job is not to describe the page itself. It controls whether a blank line is preserved after front matter during output. -## 3. 源内容 frontmatter +## 3. Source-Content Frontmatter -不同输入类型还会在自己的源文件 frontmatter 中承载描述、触发条件和工具约束等字段。多个输出插件会消费这些字段做目标元数据映射。 +Different input types also store description, trigger conditions, tool constraints, and similar fields in their own source-file frontmatter. Multiple output plugins consume those fields to map target metadata. -有一个重要例外： +There is one important exception: -- `skills` 不再从 frontmatter 读取 `name`，而是直接使用 skill 目录名 -- `subagents` 不再从 frontmatter 读取 `name`，而是直接使用相对路径推导出的名称 -- 旧的 `name` 字段如果仍然存在，会被忽略并给出告警 +- `skills` no longer read `name` from frontmatter and instead use the skill directory name directly +- `subagents` no longer read `name` from frontmatter and instead derive the name from the relative path +- If an older `name` field still exists, it is ignored and a warning is emitted -关于这些输入类型的职责边界，见 [技术细节](/docs/technical-details)。 +See [Technical Details](/docs/technical-details) for the boundary between those input types. -## 结论 +## Summary -- 文档 frontmatter 是给 docs site 的 -- `frontMatter` 配置是给输出行为的 -- 源内容 frontmatter 是给同步系统与输出插件的，但 `skills` / `subagents` 的名称现在来自路径而不是 `name` +- Docs frontmatter is for the docs site +- The `frontMatter` config is for output behavior +- Source-content frontmatter is for the sync system and output plugins, but `skills` and `subagents` now take their names from the path rather than `name` -三者不是一回事。 +These are three different concerns. diff --git a/doc/content/cli/index.mdx b/doc/content/cli/index.mdx index 37d05c97..fa8665b6 100644 --- a/doc/content/cli/index.mdx +++ b/doc/content/cli/index.mdx @@ -1,28 +1,28 @@ --- title: CLI -description: 以 tnmsc 命令面为中心组织安装、项目准备、同步流程、配置字段与排障信息。 -sidebarTitle: 概览 +description: Organizes installation, project setup, sync workflow, configuration fields, and troubleshooting around the tnmsc command surface. +sidebarTitle: Overview status: stable --- # CLI -这一节围绕 `tnmsc` 这个公开命令面组织。凡是“怎么安装”“怎么准备项目”“怎么执行同步”“某个配置字段到底是什么意思”这类问题，都优先从这里进入。 +This section is organized around the public `tnmsc` command surface. Questions such as how to install, how to prepare a project, how to run sync, or what a configuration field really means should start here first. -## 这一节包含什么 +## What This Section Covers -- [安装与前提](/docs/cli/install)：确认 Node、pnpm、Rust 与 GUI 的更高开发引擎边界。 -- [项目与 aindex](/docs/cli/workspace-setup)：准备源文件目录与项目配置入口。 -- [第一次同步](/docs/cli/first-sync)：按推荐顺序跑 `help`、`dry-run` 与真实写入。 -- [CLI 命令](/docs/cli/cli-commands)：核对 `tnmsc --help` 当前公开的命令表面。 -- [dry-run 与 clean](/docs/cli/dry-run-and-clean)：先预览、再写入、再清理。 -- [plugin.config.ts](/docs/cli/plugin-config) 与 [JSON Schema](/docs/cli/schema)：集中核对配置事实。 -- [输出范围](/docs/cli/output-scopes)、[Front Matter](/docs/cli/frontmatter)、[清理保护](/docs/cli/cleanup-protection)：确认边界控制行为。 -- [支持的输出目标](/docs/cli/supported-outputs)、[排障](/docs/cli/troubleshooting)、[升级说明](/docs/cli/upgrade-notes)：应对日常使用与版本迁移。 +- [Installation and Requirements](/docs/cli/install): confirm the Node, pnpm, Rust, and higher GUI development-engine boundaries. +- [Workspace and aindex](/docs/cli/workspace-setup): prepare the source directories and the project configuration entrypoint. +- [First Sync](/docs/cli/first-sync): run `help`, `dry-run`, and the real write flow in the recommended order. +- [CLI Commands](/docs/cli/cli-commands): check the command surface currently exposed by `tnmsc --help`. +- [dry-run and clean](/docs/cli/dry-run-and-clean): preview first, write second, clean last. +- [plugin.config.ts](/docs/cli/plugin-config) and [JSON Schema](/docs/cli/schema): verify configuration facts in one place. +- [Output Scopes](/docs/cli/output-scopes), [Front Matter](/docs/cli/frontmatter), and [Cleanup Protection](/docs/cli/cleanup-protection): confirm boundary-control behavior. +- [Supported Outputs](/docs/cli/supported-outputs), [Troubleshooting](/docs/cli/troubleshooting), and [Upgrade Notes](/docs/cli/upgrade-notes): handle day-to-day usage and version migration. -## 推荐顺序 +## Recommended Order -1. 先读 [安装与前提](/docs/cli/install)。 -2. 再读 [项目与 aindex](/docs/cli/workspace-setup)。 -3. 接着用 [第一次同步](/docs/cli/first-sync) 跑通一次真实流程。 -4. 需要核对事实时，再回看 [CLI 命令](/docs/cli/cli-commands) 与 [JSON Schema](/docs/cli/schema)。 +1. Start with [Installation and Requirements](/docs/cli/install). +2. Continue with [Workspace and aindex](/docs/cli/workspace-setup). +3. Then use [First Sync](/docs/cli/first-sync) to complete one real run. +4. When you need to verify facts, come back to [CLI Commands](/docs/cli/cli-commands) and [JSON Schema](/docs/cli/schema). diff --git a/doc/content/cli/install.mdx b/doc/content/cli/install.mdx index 77216b7d..11b2994c 100644 --- a/doc/content/cli/install.mdx +++ b/doc/content/cli/install.mdx @@ -1,7 +1,7 @@ --- -title: 安装与前提 -description: 说明 memory-sync 当前要求的 Node、pnpm、Rust 与 CLI 安装方式。 -sidebarTitle: 安装与前提 +title: Installation and Requirements +description: Explains the current Node, pnpm, Rust, and CLI installation requirements for memory-sync. +sidebarTitle: Installation and Requirements status: stable keywords: - install @@ -10,22 +10,22 @@ keywords: - rust --- -# 安装与前提 +# Installation and Requirements -## 运行时要求 +## Runtime Requirements -根据当前仓库配置： +According to the current repository configuration: -- 根工作区要求 `Node.js >= 22` -- 根工作区开发引擎要求 `pnpm 10.30.1` -- Rust workspace 目标基线为 `rust >= 1.88.0` -- `gui/` 的开发引擎要求更高，当前声明为 `rust >= 1.93.1` 与 `node >= 25.2.1` +- The root workspace requires `Node.js >= 22` +- The root workspace development engine requires `pnpm 10.30.1` +- The Rust workspace baseline is `rust >= 1.88.0` +- `gui/` requires higher development engines: currently `rust >= 1.93.1` and `node >= 25.2.1` -如果你只使用文档站与 CLI，先满足根工作区要求即可；如果你还要构建桌面 GUI，再对齐 `gui/` 的更高版本。 +If you only use the docs site and the CLI, the root workspace requirements are enough. If you also build the desktop GUI, align with the higher versions required by `gui/`. -## 安装 CLI +## Install the CLI -README 当前给出的安装方式，可以按你常用的包管理器执行： +The README currently recommends these installation commands, depending on the package manager you use: -如果你在 monorepo 本地开发，通常会直接在仓库根执行： +If you are developing inside the monorepo, you will usually run this from the repository root instead: ```sh pnpm install pnpm -C cli exec node dist/index.mjs --help ``` -## 先确认你装的是当前命令集 +## Confirm That You Installed the Current Command Set -当前 CLI 帮助里可见的核心命令是： +The core commands currently visible in CLI help are: -- 默认执行同步管线 +- the default sync pipeline - `help` - `version` -- `init`，但已经废弃 +- `init`, but deprecated - `dry-run` - `clean` - `config key=value` -这意味着旧文档里把 `tnmsc init` 当成初始化入口的说法已经过时。现在它只会返回废弃提示，不再为你生成 aindex。 +That means any older docs that still describe `tnmsc init` as the setup entrypoint are outdated. It now only returns a deprecation message and no longer generates aindex for you. -## 第一次检查 +## First Check -安装后先跑： +Run this immediately after installation: ```sh tnmsc help ``` -你应该看到 `dry-run`、`clean` 与 `config`，同时看到 `init` 被标记为 deprecated。只要这里不对，后面的文档都不该继续跟。 +You should see `dry-run`, `clean`, and `config`, with `init` marked as deprecated. If that is not what you see, stop there instead of following the rest of the docs. diff --git a/doc/content/cli/migration.mdx b/doc/content/cli/migration.mdx index c9f04980..90da4f62 100644 --- a/doc/content/cli/migration.mdx +++ b/doc/content/cli/migration.mdx @@ -1,30 +1,30 @@ --- -title: 从旧文档迁移 -description: 说明旧页面、旧命令认知与当前五大门类文档结构之间的映射关系。 -sidebarTitle: 从旧文档迁移 +title: Migrating from Older Docs +description: Explains how older pages and outdated command assumptions map onto the current top-level documentation structure. +sidebarTitle: Migrating from Older Docs status: stable --- -# 从旧文档迁移 +# Migrating from Older Docs -## 结构变化 +## Structural Changes -旧文档把“快速上手”“概念”“内容编写”“参考”“运维”混在同一层。现在一级结构改成： +Older docs mixed quick start, concepts, authoring, reference, and operations into the same layer. The new top level is: - `CLI` - `MCP` - `GUI` -- `技术细节` -- `设计初衷` +- `Technical Details` +- `Design Rationale` -这不是换名字，而是把阅读入口和写作目录按职责重新切开。 +This is not just a rename. It is a responsibility-based split between reading entrypoints and writing categories. -## 旧入口现在该去哪 +## Where Older Entry Points Go Now -- 旧的 `quick-start`、`reference`、`operations`，现在主要归到 [CLI](/docs/cli)。 -- 旧的 `concepts` 与 `authoring`，现在主要归到 [技术细节](/docs/technical-details)。 -- manifesto 类页面现在只放在 [设计初衷](/docs/design-rationale)。 +- Older `quick-start`, `reference`, and `operations` content now belongs mainly under [CLI](/docs/cli). +- Older `concepts` and `authoring` content now belongs mainly under [Technical Details](/docs/technical-details). +- Manifesto-style pages now live only under [Design Rationale](/docs/design-rationale). -## 命令认知也要一起迁移 +## Command Expectations Must Move Too -旧文档最容易误导人的地方，是把 `tnmsc init` 继续写成推荐入口。当前实现里它已经废弃，新的使用路径应以 [CLI 命令](/docs/cli/cli-commands) 为准。 +The most misleading part of the older docs is that they still present `tnmsc init` as the recommended entrypoint. In the current implementation it is deprecated, so the usage path should follow [CLI Commands](/docs/cli/cli-commands) instead. diff --git a/doc/content/cli/output-scopes.mdx b/doc/content/cli/output-scopes.mdx index 521b4a16..b2a9329a 100644 --- a/doc/content/cli/output-scopes.mdx +++ b/doc/content/cli/output-scopes.mdx @@ -1,21 +1,21 @@ --- -title: 输出范围 -description: 说明 outputScopes 如何按插件、按 topic 限制 project/global 输出范围。 -sidebarTitle: 输出范围 +title: Output Scopes +description: Explains how outputScopes restrict project and global output scopes per plugin and per topic. +sidebarTitle: Output Scopes status: stable --- -# 输出范围 +# Output Scopes -`outputScopes` 是当前实现里最重要也最容易被忽视的一个安全阀。 +`outputScopes` is one of the most important safety valves in the current implementation, and also one of the easiest to overlook. -## 它解决什么问题 +## What Problem It Solves -不是所有内容都应该被所有插件同时输出到全局和项目级。`outputScopes` 让你可以按插件、按 topic 指定来源范围。 +Not every piece of content should be emitted by every plugin to both global and project destinations. `outputScopes` lets you declare the source scope by plugin and by topic. -## 支持的 topic +## Supported Topics -当前核心常量与 Schema 对齐，支持： +The current core constants and schema support: - `prompt` - `rules` @@ -24,14 +24,14 @@ status: stable - `skills` - `mcp` -## 可选范围 +## Allowed Scopes - `project` - `global` -有些 topic 允许多值数组，有些插件会声明为单值 topic。如果你给单值 topic 传多个范围，运行前校验会直接报错。 +Some topics allow multi-value arrays, while some plugins declare a topic as single-valued. If you pass multiple scopes to a single-valued topic, validation fails before execution. -## 示例 +## Example ```json { @@ -46,12 +46,12 @@ status: stable } ``` -## 什么时候该先看它 +## When to Check It First -当你遇到这些现象时： +Look here first when you see any of these: -- 规则被写进了全局配置，但你只想要项目级 -- 全局 Prompt 被错误地带进某个局部目标 -- 技能、命令或 MCP 相关输出出现在不该出现的目标里 +- Rules are written into global config even though you only wanted project-level output +- A global prompt is incorrectly pulled into a local target +- Skill, command, or MCP-related outputs appear in targets where they do not belong -优先检查 `outputScopes`，不要先改源文件本身。 +Check `outputScopes` before you edit the source files themselves. diff --git a/doc/content/cli/plugin-config.mdx b/doc/content/cli/plugin-config.mdx index 1e0bf530..68253618 100644 --- a/doc/content/cli/plugin-config.mdx +++ b/doc/content/cli/plugin-config.mdx @@ -1,25 +1,25 @@ --- title: plugin.config.ts -description: 说明项目级 plugin.config.ts 如何装配默认输出插件与运行参数。 +description: Explains how the project-level plugin.config.ts assembles default output plugins and runtime options. sidebarTitle: plugin.config.ts status: stable --- # `plugin.config.ts` -## 它的职责 +## What It Does -`plugin.config.ts` 是项目级装配入口。它把： +`plugin.config.ts` is the project-level assembly entrypoint. It passes: -- 管线参数 -- 插件列表 -- 可能的程序化覆盖 +- pipeline options +- the plugin list +- any programmatic overrides -交给 `defineConfig()`，最终产出真正执行同步所需的 `PipelineConfig`。 +into `defineConfig()`, which produces the `PipelineConfig` used for real execution. -## 当前默认输出插件 +## Current Default Output Plugins -当前仓库 `sdk/src/plugin.config.ts` 默认装配的输出插件包括： +The default output plugins currently assembled in `sdk/src/plugin.config.ts` include: - `AgentsOutputPlugin` - `ClaudeCodeCLIOutputPlugin` @@ -27,7 +27,7 @@ status: stable - `JetBrainsAIAssistantCodexOutputPlugin` - `DroidCLIOutputPlugin` - `GeminiCLIOutputPlugin` -- `GenericSkillsOutputPlugin`（deprecated，保留用于兼容旧技能分发；清理时需要连同全局 `~/.skills/` 整个目录一起移除） +- `GenericSkillsOutputPlugin` (deprecated, kept only for compatibility with older skill distribution; cleanup must also remove the global `~/.skills/` directory) - `OpencodeCLIOutputPlugin` - `QoderIDEPluginOutputPlugin` - `TraeIDEOutputPlugin` @@ -41,14 +41,14 @@ status: stable - `VisualStudioCodeIDEConfigOutputPlugin` - `ReadmeMdConfigFileOutputPlugin` -## 这意味着什么 +## What That Means -这份配置不是“文档示意”，而是当前默认同步现实。只要这里有插件，就意味着默认执行里会考虑该目标。 +This configuration is not illustrative documentation. It is the current default sync reality. If a plugin appears here, the default execution path considers that target. -## 最小认知模型 +## Minimal Mental Model -你可以把 `plugin.config.ts` 理解为： +You can think of `plugin.config.ts` as the file that: -- 选择要输出到哪些目标 -- 决定是否在项目里追加程序化配置 -- 保持与全局用户配置合并，而不是完全绕开用户配置 +- chooses which targets receive outputs +- decides whether to append programmatic config at the project level +- keeps project config merged with global user config rather than bypassing it entirely diff --git a/doc/content/cli/schema.mdx b/doc/content/cli/schema.mdx index 92e21742..e0b5e299 100644 --- a/doc/content/cli/schema.mdx +++ b/doc/content/cli/schema.mdx @@ -1,27 +1,27 @@ --- title: JSON Schema -description: 梳理 tnmsc.schema.json 当前公开的配置字段与约束。 +description: Summarizes the configuration fields and constraints currently exposed by tnmsc.schema.json. sidebarTitle: JSON Schema status: stable --- # JSON Schema -`cli/dist/tnmsc.schema.json` 当前公开的根字段有： +`cli/dist/tnmsc.schema.json` currently exposes these root fields: -| 字段 | 类型 | 说明 | +| Field | Type | Description | | --- | --- | --- | -| `version` | `string` | 配置版本或发布版本标记 | -| `workspaceDir` | `string` | 项目根目录 | -| `aindex` | `object` | 输入源与导出目录映射 | +| `version` | `string` | Config version or release version marker | +| `workspaceDir` | `string` | Project root directory | +| `aindex` | `object` | Mapping of source inputs to export directories | | `logLevel` | enum | `trace` / `debug` / `info` / `warn` / `error` | -| `commandSeriesOptions` | `object` | command 系列命名与插件覆盖 | -| `outputScopes` | `object` | 各插件输出范围覆盖 | -| `frontMatter` | `object` | 输出时的 front matter 处理选项 | -| `cleanupProtection` | `object` | 清理保护规则 | -| `profile` | `object` | 个人资料字段 | +| `commandSeriesOptions` | `object` | Command-series naming and per-plugin overrides | +| `outputScopes` | `object` | Output-scope overrides per plugin | +| `frontMatter` | `object` | Front matter handling during output | +| `cleanupProtection` | `object` | Cleanup protection rules | +| `profile` | `object` | Profile fields | -## `aindex` 下的关键子项 +## Key `aindex` Children - `skills` - `commands` @@ -33,11 +33,11 @@ status: stable - `ext` - `arch` -每个子项都由 `src` / `dist` 组成。 +Each child contains `src` and `dist`. -## `outputScopes` 支持的 topic +## Topics Supported by `outputScopes` -Schema 当前允许的 topic 包括： +The schema currently allows these topics: - `prompt` - `rules` @@ -46,11 +46,11 @@ Schema 当前允许的 topic 包括： - `skills` - `mcp` -详细行为见 [输出范围](/docs/cli/output-scopes)。 +See [Output Scopes](/docs/cli/output-scopes) for detailed behavior. ## `frontMatter` -当前公开字段只有一个： +The only public field right now is: ```json { @@ -60,15 +60,15 @@ Schema 当前允许的 topic 包括： } ``` -详细区分见 [Front Matter](/docs/cli/frontmatter)。 +See [Front Matter](/docs/cli/frontmatter) for the distinction. ## `cleanupProtection` -每条规则支持： +Each rule supports: - `path` - `protectionMode`: `direct` / `recursive` - `matcher`: `path` / `glob` - `reason` -详细语义见 [清理保护](/docs/cli/cleanup-protection)。 +See [Cleanup Protection](/docs/cli/cleanup-protection) for the semantics. diff --git a/doc/content/cli/supported-outputs.mdx b/doc/content/cli/supported-outputs.mdx index f94b7b3c..0351883a 100644 --- a/doc/content/cli/supported-outputs.mdx +++ b/doc/content/cli/supported-outputs.mdx @@ -1,17 +1,17 @@ --- -title: 支持的输出目标 -description: 按当前默认 plugin.config.ts 汇总 memory-sync 已接入的输出目标。 -sidebarTitle: 支持的输出目标 +title: Supported Outputs +description: Summarizes the output targets currently integrated by the default plugin.config.ts. +sidebarTitle: Supported Outputs status: stable --- -# 支持的输出目标 +# Supported Outputs -当前默认插件配置说明，项目已经接入的输出目标至少包括： +The current default plugin configuration shows that the project is integrated with at least these output targets: -## AI / IDE / CLI 目标 +## AI / IDE / CLI Targets -- AGENTS.md 风格输出 +- AGENTS.md-style output - Claude Code CLI - OpenAI Codex CLI - Gemini CLI @@ -25,15 +25,15 @@ status: stable - Trae CN - JetBrains AI Assistant Codex -## 通用辅助输出 +## Generic Support Outputs -- Generic Skills 导出 +- Generic Skills export - `.git/info/exclude` - `.editorconfig` -- VS Code 配置 -- JetBrains code style 配置 -- README 类输出 +- VS Code config +- JetBrains code style config +- README-like outputs -## 一件要特别记住的事 +## One Important Thing to Remember -README 里的 “Supported Tools” 表是面向用户的高层描述；真正影响默认同步行为的，是 [plugin.config.ts](/docs/cli/plugin-config) 里装配了哪些插件。两者冲突时，以后者为准。 +The "Supported Tools" table in the README is a high-level user-facing description. The thing that actually controls default sync behavior is which plugins are assembled in [plugin.config.ts](/docs/cli/plugin-config). If the two disagree, trust the latter. diff --git a/doc/content/cli/troubleshooting.mdx b/doc/content/cli/troubleshooting.mdx index d07126b7..3efa63e7 100644 --- a/doc/content/cli/troubleshooting.mdx +++ b/doc/content/cli/troubleshooting.mdx @@ -1,43 +1,43 @@ --- -title: 排障 -description: 整理当前最可能遇到的版本、命令与输出范围问题。 -sidebarTitle: 排障 +title: Troubleshooting +description: Collects the version, command, and output-scope problems you are most likely to run into right now. +sidebarTitle: Troubleshooting status: stable --- -# 排障 +# Troubleshooting -## 现象：我以为有某个页面，结果 404 +## Symptom: I Expected a Page, but I Got a 404 -新文档已经从旧的混合分组改成七个一级门类。优先从 [/docs](/docs) 或 [快速指引](/docs/quick-guide) 开始找，而不是沿用旧路径。 +The docs have moved from the old mixed grouping into seven top-level sections. Start from [/docs](/docs) or the [Quick Guide](/docs/quick-guide) instead of following older paths. -## 现象：`tnmsc init` 没帮我生成任何内容 +## Symptom: `tnmsc init` Did Not Generate Anything -这是当前实现预期行为。它已经废弃，不再初始化 aindex。请改为手动维护你的源目录和全局配置。 +That is expected in the current implementation. It is deprecated and no longer initializes aindex. Maintain your source directories and global config manually instead. -## 现象：规则、Prompt 或 MCP 相关内容输出到了不该出现的地方 +## Symptom: Rules, Prompts, or MCP-Related Content Was Written to the Wrong Place -先检查： +Check these first: -1. [plugin.config.ts](/docs/cli/plugin-config) 中到底装了哪些输出插件。 -2. [输出范围](/docs/cli/output-scopes) 有没有按 topic 限制范围。 -3. 你写的是 global 还是项目 Prompt 源。 +1. Which output plugins are actually assembled in [plugin.config.ts](/docs/cli/plugin-config). +2. Whether [Output Scopes](/docs/cli/output-scopes) limits the topic correctly. +3. Whether you authored a global prompt or a workspace prompt. -## 现象：`clean` 不敢执行或执行后删过头 +## Symptom: `clean` Feels Unsafe or Deleted Too Much -先回看 [清理保护](/docs/cli/cleanup-protection)。如果目录里混有人工文件，却没配置保护规则，`clean` 风险就会明显升高。 +Review [Cleanup Protection](/docs/cli/cleanup-protection) first. If your directories mix manual files with generated files and you do not configure protection rules, the risk of `clean` rises quickly. -## 现象：文档页构建失败 +## Symptom: A Docs Page Fails to Build -先跑： +Run this first: ```sh pnpm -C doc run validate:content ``` -这套校验会先检查： +This validation step checks: -- 每个 MDX 是否有 `title` / `description` -- 每个内容目录是否有 `_meta.ts` -- `_meta.ts` 是否覆盖当前文件与子目录 -- 文档内部链接是否指向存在的页面 +- Whether every MDX file has `title` and `description` +- Whether every content directory has `_meta.ts` +- Whether `_meta.ts` covers the current files and subdirectories +- Whether internal docs links point to real pages diff --git a/doc/content/cli/upgrade-notes.mdx b/doc/content/cli/upgrade-notes.mdx index 2e886827..276e0be0 100644 --- a/doc/content/cli/upgrade-notes.mdx +++ b/doc/content/cli/upgrade-notes.mdx @@ -1,30 +1,30 @@ --- -title: 升级说明 -description: 汇总当前文档结构、命令认知与运行边界中最需要注意的升级点。 -sidebarTitle: 升级说明 +title: Upgrade Notes +description: Summarizes the most important upgrades in the current docs structure, command expectations, and runtime boundaries. +sidebarTitle: Upgrade Notes status: stable --- -# 升级说明 +# Upgrade Notes -## 文档结构升级 +## Docs Structure Upgrade -文档站已经从“快速上手 / 概念 / 内容编写 / 参考 / 运维”的混合结构，重排为： +The docs site has been reorganized from a mixed structure of quick start, concepts, authoring, reference, and operations into: - `CLI` - `MCP` - `GUI` -- `技术细节` -- `设计初衷` +- `Technical Details` +- `Design Rationale` -如果你在维护页面或补文档，请先按这五类放置目录，再开始写内容。 +If you are maintaining or adding pages, place them under one of those five categories before you start writing. -## 命令认知升级 +## Command Model Upgrade -- `tnmsc init` 不再是初始化入口 -- `dry-run` 应作为默认验证动作 -- `clean --dry-run` 应作为默认清理前检查 +- `tnmsc init` is no longer the initialization entrypoint +- `dry-run` should be the default validation step +- `clean --dry-run` should be the default pre-clean check -## 运行边界升级 +## Runtime Boundary Upgrade -仓库的长期方向仍然是 Rust-first / NAPI-first。TypeScript 在这里更偏接口暴露、配置装配、桥接运行时和声明层，而不是长期核心实现中心。 +The long-term direction of the repository is still Rust-first / NAPI-first. TypeScript is primarily for exposed interfaces, configuration assembly, bridge runtime logic, and declarations rather than the long-term center of the core implementation. diff --git a/doc/content/cli/workspace-setup.mdx b/doc/content/cli/workspace-setup.mdx index 2ae5fe61..26019f10 100644 --- a/doc/content/cli/workspace-setup.mdx +++ b/doc/content/cli/workspace-setup.mdx @@ -1,39 +1,39 @@ --- -title: 项目与 aindex -description: 说明 aindex 源目录、全局配置与项目配置入口在当前仓库中的职责分工。 -sidebarTitle: 项目与 aindex +title: Workspace and aindex +description: Explains how the aindex source directory, global config, and project config entrypoint divide responsibilities in the current repo. +sidebarTitle: Workspace and aindex status: stable --- -# 项目与 aindex +# Workspace and aindex -## 先记住这件事 +## Remember This First -`memory-sync` 不是把目标工具配置文件当真源维护，而是围绕 aindex 源目录与项目配置入口来生成目标输出。 +`memory-sync` does not treat target-tool config files as the source of truth. It generates outputs from the aindex source directory and the project configuration entrypoint. -## 你至少需要准备什么 +## What You Need at Minimum -- 一个项目根目录 -- aindex 风格的源内容目录 -- 全局配置文件 -- 项目级 `plugin.config.ts` +- A project root directory +- An aindex-style source-content directory +- A global config file +- A project-level `plugin.config.ts` -## 源内容通常怎么分 +## How Source Content Is Usually Split -当前文档里单独拆出的输入资产包括： +The input assets documented separately right now are: -- 全局 Prompt 与项目 Prompt +- Global prompts and workspace prompts - `skills/` - `commands/` - `subagents/` - `rules/` -这些输入资产的职责说明在 [技术细节](/docs/technical-details) 里统一解释，而 CLI 侧只负责告诉你它们会被怎样读取、校验和写出。 +Their responsibility boundaries are explained in [Technical Details](/docs/technical-details). The CLI docs focus only on how those assets are read, validated, and written out. -## 项目配置入口 +## Project Configuration Entrypoint -项目级装配入口是 [plugin.config.ts](/docs/cli/plugin-config)。它决定默认装配哪些输出插件，以及项目级运行参数如何并入真实执行配置。 +The project-level assembly entrypoint is [plugin.config.ts](/docs/cli/plugin-config). It decides which output plugins are assembled by default and how project-level runtime options are merged into the real execution config. -## 下一步 +## Next Step -目录准备完后，直接进入 [第一次同步](/docs/cli/first-sync)，先用 `dry-run` 验证输出范围，再做真实写入。 +Once the directories are ready, continue to [First Sync](/docs/cli/first-sync). Use `dry-run` to validate the output scope before doing a real write. diff --git a/doc/content/design-rationale/_meta.ts b/doc/content/design-rationale/_meta.ts index a100bf3b..6425ae35 100644 --- a/doc/content/design-rationale/_meta.ts +++ b/doc/content/design-rationale/_meta.ts @@ -1,4 +1,4 @@ export default { - index: '概览', - manifesto: '为什么要做这个工具' + index: 'Overview', + manifesto: 'Why This Tool Exists' } diff --git a/doc/content/design-rationale/index.mdx b/doc/content/design-rationale/index.mdx index bde1fa7d..a8e2883d 100644 --- a/doc/content/design-rationale/index.mdx +++ b/doc/content/design-rationale/index.mdx @@ -1,21 +1,21 @@ --- -title: 设计初衷 -description: 单独收纳项目动机、设计理由与 manifesto 类内容，避免与使用说明和实现细节混写。 -sidebarTitle: 概览 +title: Design Rationale +description: Separates project motivation, design reasoning, and manifesto-style content from usage docs and implementation details. +sidebarTitle: Overview status: stable --- -# 设计初衷 +# Design Rationale -这一节只处理“为什么这样做”，不承担安装、命令、Schema 或页面工作流说明。 +This section answers only why the project is shaped this way. It does not own installation, command, schema, or page-workflow explanations. -## 为什么要单独分出来 +## Why This Section Exists Separately -因为背景叙事一旦和操作文档混在一起，会同时伤害两件事： +Once background narrative is mixed into operational docs, two things get worse at the same time: -- 用户很难快速进入最短使用路径 -- 维护者很容易把理念页写进功能页，导致 IA 再次失焦 +- Users struggle to reach the shortest working path quickly +- Maintainers start writing idea pages into feature pages, and the information architecture loses focus again -## 当前入口 +## Current Entry -- [为什么要做这个工具](/docs/design-rationale/manifesto) +- [Why This Tool Exists](/docs/design-rationale/manifesto) diff --git a/doc/content/design-rationale/manifesto.mdx b/doc/content/design-rationale/manifesto.mdx index a2939f66..75e7fdd7 100644 --- a/doc/content/design-rationale/manifesto.mdx +++ b/doc/content/design-rationale/manifesto.mdx @@ -1,41 +1,41 @@ --- -title: 为什么要做这个工具 -description: 从 README 的 tool-rat 叙事出发，解释 memory-sync 试图解决的真实问题。 -sidebarTitle: 为什么要做这个工具 +title: Why This Tool Exists +description: Starts from the README's tool-rat framing and explains the real problem memory-sync is trying to solve. +sidebarTitle: Why This Tool Exists status: stable --- -# 为什么要做这个工具 +# Why This Tool Exists -README 对 `memory-sync` 的核心定位写得很直接：这不是一个等待平台统一标准的工具，而是一个默认世界碎片化、接口私有化、资源分配极不公平时仍然能工作的 “tool-rat”。 +The README describes the core positioning of `memory-sync` very directly: this is not a tool that waits for platforms to converge on a shared standard. It is a "tool-rat" that still works in a world where tools are fragmented, interfaces are private, and access is distributed unfairly. -## 项目不是在卖什么 +## What the Project Is Not Promising -它不承诺： +It does not promise: -- 某个 IDE 或 CLI 最终会给你一套官方统一入口。 -- 某家平台会长久稳定地保存你的工作记忆。 -- 复制粘贴几份提示词就等于真正完成了迁移。 +- That a specific IDE or CLI will eventually give you one official unified entrypoint +- That some platform will preserve your working memory reliably forever +- That copying and pasting a few prompts is the same thing as a real migration -## 项目真正要做的事 +## What the Project Is Actually Trying to Do -它要做的是： +Its goal is to: -1. 把你原本散落在多个工具里的规则源抽离出来。 -2. 让这些规则源有统一的编写方式。 -3. 再把它们重新投送回不同工具的原生落点。 +1. Pull rule sources out of the tools where they are currently scattered. +2. Give those rule sources one consistent authoring model. +3. Deliver them back into the native locations required by different tools. -## 为什么这件事必须是“同步系统”，不是“模板仓库” +## Why This Must Be a Sync System Instead of a Template Repository -仅有模板仓库，你依旧要手动： +With only a template repository, you still have to do all of this by hand: -- 决定每个工具写到哪里 -- 决定哪些内容是全局的、哪些是项目级的 -- 决定怎样清掉旧产物 -- 决定如何避免多套配置互相踩踏 +- Decide where each tool should receive output +- Decide what is global and what is project-specific +- Decide how to remove old artifacts +- Decide how to keep multiple configurations from stepping on each other -而 `memory-sync` 的重点，是把这些判断前移到可声明的配置与源文件结构里。 +The point of `memory-sync` is to move those decisions forward into declarative configuration and source-file structure. -## 所以文档为什么也要重写 +## Why the Docs Had to Be Rewritten Too -如果文档还沿用旧的、松散的、不能映射到真实实现的叙述方式，那它本身就会变成新的“残留物”。这次重构的文档站，本质上也是把 docs 自己纳入“可验证输出”的同一套纪律里。 +If the docs kept the old loose narrative that could not map back to the real implementation, the docs themselves would become new residue. The docs-site rewrite is really the same discipline applied to docs: make them verifiable against the implementation instead of letting them drift. diff --git a/doc/content/gui/_meta.ts b/doc/content/gui/_meta.ts index 0fdf6aa6..04f025ea 100644 --- a/doc/content/gui/_meta.ts +++ b/doc/content/gui/_meta.ts @@ -1,4 +1,4 @@ export default { - 'index': '概览', - 'workflows-and-pages': '页面与工作流' + 'index': 'Overview', + 'workflows-and-pages': 'Workflows and Pages' } diff --git a/doc/content/gui/index.mdx b/doc/content/gui/index.mdx index 53cf36ae..f79c6cb4 100644 --- a/doc/content/gui/index.mdx +++ b/doc/content/gui/index.mdx @@ -1,36 +1,36 @@ --- title: GUI -description: 说明 Tauri 桌面层的职责、边界，以及它与 sdk / tnmsc crate / CLI 的关系。 -sidebarTitle: 概览 +description: Explains the responsibilities and boundaries of the Tauri desktop layer, and how it relates to sdk, the tnmsc crate, and the CLI. +sidebarTitle: Overview status: stable --- # GUI -`gui/` 是基于 Tauri + React 的桌面调用层。它的角色不是成为系统架构中心，而是把 `sdk/` 中 `tnmsc` crate 暴露的配置编辑、执行、展示与日志观察做成桌面工作流。 +`gui/` is the desktop invocation layer built with Tauri and React. Its job is not to become the center of the system architecture. Its job is to turn the configuration editing, execution, display, and log inspection exposed by the `tnmsc` crate in `sdk/` into a desktop workflow. -## 这层负责什么 +## What This Layer Owns -- 发起同步、`dry-run` 与清理 -- 编辑或展示配置 -- 浏览文件、插件结果与日志 -- 提供桌面端页面化工作流 +- Trigger sync, `dry-run`, and cleanup +- Edit or display config +- Browse files, plugin results, and logs +- Provide a page-based desktop workflow -## 这层不负责什么 +## What This Layer Does Not Own -- 不重新实现 sync core -- 不在前端重新推导 CLI 规则 -- 不改变 Rust-first / NAPI-first 的长期方向 +- It does not reimplement the sync core +- It does not re-derive CLI rules in the frontend +- It does not change the long-term Rust-first / NAPI-first direction -## 版本边界 +## Version Boundary -当前 `gui/package.json` 对开发引擎要求高于根工作区： +`gui/package.json` currently requires higher development engines than the root workspace: - `node >= 25.2.1` - `pnpm >= 10.28.0` - `rust >= 1.93.1` -## 推荐阅读 +## Recommended Reading -- [页面与工作流](/docs/gui/workflows-and-pages)：查看当前导航、主要页面与桌面工作流。 -- [技术细节 / 架构边界](/docs/technical-details/architecture)：理解 GUI 为什么只能是调用层而不是核心层。 +- [Workflows and Pages](/docs/gui/workflows-and-pages): see the current navigation, main pages, and desktop workflow +- [Technical Details / Architecture Boundaries](/docs/technical-details/architecture): understand why the GUI is an invocation layer rather than the core diff --git a/doc/content/gui/workflows-and-pages.mdx b/doc/content/gui/workflows-and-pages.mdx index 096ae8f7..f833c6ea 100644 --- a/doc/content/gui/workflows-and-pages.mdx +++ b/doc/content/gui/workflows-and-pages.mdx @@ -1,15 +1,15 @@ --- -title: 页面与工作流 -description: 汇总当前 GUI 的导航入口、主要页面和与同步流程直接相关的桌面操作面。 -sidebarTitle: 页面与工作流 +title: Workflows and Pages +description: Summarizes the current GUI navigation, main pages, and the desktop surfaces directly tied to the sync flow. +sidebarTitle: Workflows and Pages status: stable --- -# 页面与工作流 +# Workflows and Pages -## 当前主导航 +## Current Main Navigation -`gui/src/components/Sidebar.tsx` 当前注册的导航项包括： +`gui/src/components/Sidebar.tsx` currently registers these navigation items: - Dashboard - Pipeline @@ -19,20 +19,20 @@ status: stable - Logs - Settings -## 这些页面说明了什么 +## What These Pages Mean -- Dashboard：展示统计、快速动作和受支持工具概览 -- Pipeline：执行同步、`dry-run`，并查看插件结果与错误 -- Config：查看或编辑配置入口 -- Plugins / Files / Logs：分别面向插件结果、文件视图与日志观察 -- Settings：桌面侧偏好与设置入口 +- Dashboard: stats, quick actions, and a supported-tools overview +- Pipeline: run sync and `dry-run`, then inspect plugin results and errors +- Config: view or edit configuration +- Plugins / Files / Logs: plugin results, file views, and log inspection +- Settings: desktop-side preferences and settings -## 和 CLI 的关系 +## Relationship to the CLI -桌面页面并没有单独定义一套 sync 规则。它主要通过桥接层调用底层能力，把命令式流程转成页面式工作流。 +The desktop pages do not define a separate set of sync rules. They primarily call the lower-level capability through the bridge layer and turn command-style flows into page-style workflows. -因此，遇到这些问题时仍然应先回到 CLI 文档： +That is why you should still return to the CLI docs first when these questions come up: -- 命令表面是否变了：看 [CLI 命令](/docs/cli/cli-commands) -- 输出范围是否正确：看 [输出范围](/docs/cli/output-scopes) -- 清理边界是否安全：看 [清理保护](/docs/cli/cleanup-protection) +- Has the command surface changed? See [CLI Commands](/docs/cli/cli-commands) +- Is the output scope correct? See [Output Scopes](/docs/cli/output-scopes) +- Is the cleanup boundary safe? See [Cleanup Protection](/docs/cli/cleanup-protection) diff --git a/doc/content/index.mdx b/doc/content/index.mdx index 0c9c657d..ccc04cb7 100644 --- a/doc/content/index.mdx +++ b/doc/content/index.mdx @@ -1,6 +1,6 @@ --- title: overview -description: memory-sync 文档入口，按快速指引、CLI、SDK、MCP、GUI、技术细节与设计初衷七个一级门类组织。 +description: Entry page for the memory-sync docs, organized into Quick Guide, CLI, SDK, MCP, GUI, Technical Details, and Design Rationale. sidebarTitle: overview status: stable keywords: @@ -9,34 +9,34 @@ keywords: - overview --- -# 文档总览 +# Docs Overview -这套文档站围绕当前仓库事实组织，一级结构固定为 `快速指引`、`CLI`、`SDK`、`MCP`、`GUI`、`技术细节`、`设计初衷`。这样写文档时，第一次进入的最短路径、面向用户的操作入口、repo 内部 mixed core、面向集成的 server、桌面层说明、实现原理和背景动机不再混在一起。 +This docs site is organized around the current repository as it actually exists. The top-level structure is fixed as `Quick Guide`, `CLI`, `SDK`, `MCP`, `GUI`, `Technical Details`, and `Design Rationale`. That keeps the shortest onboarding path, the user-facing operation surface, the internal mixed core, the integration server, the desktop layer, implementation details, and project motivation from collapsing into one bucket. -## 七个一级门类 +## The Seven Top-Level Sections -| 门类 | 主要回答的问题 | 入口 | +| Section | Main Question | Entry | | --- | --- | --- | -| 快速指引 | 我现在该从 CLI、GUI 还是 MCP 开始，最短路径分别是什么 | [快速指引](/docs/quick-guide) | -| CLI | 如何安装、准备项目、执行同步、理解命令与配置字段 | [CLI](/docs/cli) | -| SDK | `sdk/` 为什么是 mixed core、拥有哪些能力、内部消费者该如何依赖它 | [SDK](/docs/sdk) | -| MCP | `memory-sync-mcp` 是什么、暴露了哪些工具、适合怎么接入 | [MCP](/docs/mcp) | -| GUI | 桌面层负责什么、有哪些页面、它与 `sdk/` / `tnmsc` crate / CLI 如何配合 | [GUI](/docs/gui) | -| 技术细节 | 架构边界、同步管线、真源模型，以及 prompts / skills / commands / rules 等输入资产如何组织 | [技术细节](/docs/technical-details) | -| 设计初衷 | 为什么要做这个项目，为什么文档也要这样分层 | [设计初衷](/docs/design-rationale) | - -## 从哪里开始 - -- 第一次进入文档站，先看 [快速指引](/docs/quick-guide)，先判断你要走 CLI、GUI 还是 MCP 路径。 -- 第一次使用 `memory-sync` 的同步能力，再进入 [CLI](/docs/cli)，把安装、项目准备和第一次同步跑通。 -- 需要理解 repo 内部核心层怎么分工、为什么以后统一复用 `sdk/`，先看 [SDK](/docs/sdk)。 -- 需要把 `memory-sync-mcp` 接入到支持 MCP 的宿主里，直接进 [MCP](/docs/mcp)。 -- 关注桌面应用而不是终端入口时，查看 [GUI](/docs/gui)。 -- 需要理解 Rust-first / NAPI-first、真源模型和输入资产职责时，进入 [技术细节](/docs/technical-details)。 -- 需要项目背景、动机和设计理由时，再补读 [设计初衷](/docs/design-rationale)。 - -## 文档边界 - -- 文档以仓库当前可验证实现为准，不把未落地的自动化、页面或工作流写成既成事实。 -- 当前公开文档以中文为权威版本；命令、API 名称和关键术语保持英文。 -- 如果 README、旧页面和当前实现冲突，这里优先跟随 `tnmsc --help`、Schema、目录结构和实际代码。 +| Quick Guide | Should I start with CLI, GUI, or MCP, and what is the shortest path for each? | [Quick Guide](/docs/quick-guide) | +| CLI | How do I install, prepare a project, run sync, and understand the commands and config fields? | [CLI](/docs/cli) | +| SDK | Why is `sdk/` the mixed core, what does it own, and how should internal consumers depend on it? | [SDK](/docs/sdk) | +| MCP | What is `memory-sync-mcp`, which tools does it expose, and how should it be integrated? | [MCP](/docs/mcp) | +| GUI | What does the desktop layer own, which pages exist, and how does it work with `sdk/`, the `tnmsc` crate, and the CLI? | [GUI](/docs/gui) | +| Technical Details | How are the architecture boundaries, sync pipeline, source-of-truth model, and input assets such as prompts, skills, commands, and rules organized? | [Technical Details](/docs/technical-details) | +| Design Rationale | Why does this project exist, and why are the docs layered this way? | [Design Rationale](/docs/design-rationale) | + +## Where to Start + +- If this is your first time opening the docs site, start with the [Quick Guide](/docs/quick-guide) and decide whether you need the CLI, GUI, or MCP path. +- If you want to use `memory-sync` for real work right away, continue into [CLI](/docs/cli) and get installation, project setup, and the first sync run working. +- If you need to understand how the internal core is split and why `sdk/` is now the shared center, go to [SDK](/docs/sdk). +- If you want to integrate `memory-sync-mcp` into an MCP-capable host, jump straight to [MCP](/docs/mcp). +- If you care about the desktop app rather than the terminal surface, open [GUI](/docs/gui). +- If you need the Rust-first / NAPI-first direction, the source-of-truth model, and the asset boundaries, go to [Technical Details](/docs/technical-details). +- If you need the project background, motivation, and design reasoning, finish with [Design Rationale](/docs/design-rationale). + +## Documentation Boundaries + +- The docs follow the repository's currently verifiable implementation and do not present unshipped automation, pages, or workflows as facts. +- Command names, API names, and key technical terms remain in English. +- If the README, older pages, and the current implementation disagree, this site follows `tnmsc --help`, the schema, the directory structure, and the actual code. diff --git a/doc/content/mcp/_meta.ts b/doc/content/mcp/_meta.ts index b54b703e..32df850f 100644 --- a/doc/content/mcp/_meta.ts +++ b/doc/content/mcp/_meta.ts @@ -1,4 +1,4 @@ export default { - 'index': '概览', - 'server-tools': 'Server 与 Tools' + 'index': 'Overview', + 'server-tools': 'Server and Tools' } diff --git a/doc/content/mcp/index.mdx b/doc/content/mcp/index.mdx index d75a160b..30ff4835 100644 --- a/doc/content/mcp/index.mdx +++ b/doc/content/mcp/index.mdx @@ -1,28 +1,28 @@ --- title: MCP -description: 说明 memory-sync-mcp 的定位、运行方式，以及它与 sdk prompt service 的关系。 -sidebarTitle: 概览 +description: Explains the role of memory-sync-mcp, how it runs, and how it relates to the sdk prompt service. +sidebarTitle: Overview status: stable --- # MCP -`mcp/` 是当前仓库里的独立包，发布名为 `@truenine/memory-sync-mcp`，可执行入口是 `memory-sync-mcp`。它不是文档里的抽象概念，而是一个真实存在的 stdio server。 +`mcp/` is a standalone package in the current repository. It is published as `@truenine/memory-sync-mcp`, and its executable entrypoint is `memory-sync-mcp`. It is not an abstract concept from the docs. It is a real stdio server. -## 它负责什么 +## What It Owns -- 作为 MCP stdio server 暴露 `memory-sync` 的 prompt 管理能力 -- 复用 `@truenine/memory-sync-sdk` 导出的 prompt service，而不是重新实现一套独立逻辑 -- 让支持 MCP 的宿主按工具调用方式读取、更新和写回 prompt 资产 +- It exposes `memory-sync` prompt-management capability as an MCP stdio server +- It reuses the prompt service exported by `@truenine/memory-sync-sdk` instead of reimplementing separate logic +- It lets MCP-capable hosts read, update, and write back prompt assets through tool calls -## 它不负责什么 +## What It Does Not Own -- 它不是新的真源格式 -- 它不是 GUI 的替代品 -- 它不是绕过 CLI 规则的“特权入口” +- It is not a new source-of-truth format +- It is not a replacement for the GUI +- It is not a privileged path that bypasses CLI rules -## 推荐阅读 +## Recommended Reading -- [Server 与 Tools](/docs/mcp/server-tools)：查看 stdio server 的入口、工具清单与 `workspaceDir` 语义。 -- [CLI](/docs/cli)：需要了解项目准备、Schema 与输出边界时，仍然回到 CLI 侧核对事实。 -- [技术细节](/docs/technical-details/source-of-truth)：需要理解 prompt 资产为什么这样建模时，从真源模型开始。 +- [Server and Tools](/docs/mcp/server-tools): see the stdio server entrypoints, tool list, and `workspaceDir` semantics +- [CLI](/docs/cli): return there when you need project setup, schema details, or output boundaries +- [Technical Details](/docs/technical-details/source-of-truth): start from the source-of-truth model when you need to understand why prompt assets are modeled this way diff --git a/doc/content/mcp/server-tools.mdx b/doc/content/mcp/server-tools.mdx index 700d17b1..73f6db7c 100644 --- a/doc/content/mcp/server-tools.mdx +++ b/doc/content/mcp/server-tools.mdx @@ -1,69 +1,69 @@ --- -title: Server 与 Tools -description: 说明 memory-sync-mcp 的 stdio server 入口、四个已暴露工具，以及 workspaceDir 的作用。 -sidebarTitle: Server 与 Tools +title: Server and Tools +description: Explains the memory-sync-mcp stdio server entrypoints, the four exposed tools, and the role of workspaceDir. +sidebarTitle: Server and Tools status: stable --- -# Server 与 Tools +# Server and Tools -## 公开入口 +## Public Entrypoints -`mcp/src/index.ts` 当前只公开两个入口： +`mcp/src/index.ts` currently exposes only two entrypoints: - `createMemorySyncMcpServer` - `runMemorySyncMcpStdioServer` -这说明这个包的职责非常明确，就是提供 server 构造与 stdio 运行入口。 +That makes the package boundary very clear: it provides server construction and the stdio runtime entrypoint. -## 当前已暴露的工具 +## Currently Exposed Tools -`mcp/src/server.ts` 当前注册的工具包括： +`mcp/src/server.ts` currently registers these tools: - `list_prompts` - `get_prompt` - `upsert_prompt_src` - `apply_prompt_translation` -## 每个工具大致负责什么 +## What Each Tool Does at a High Level -## `workspaceDir` 的作用 +## What `workspaceDir` Does -这些工具都接受可选的 `workspaceDir`。它的语义不是“随便切目录”，而是把 prompt service 的项目根显式绑定到某个项目上下文。 +All of these tools accept an optional `workspaceDir`. Its meaning is not "switch directories arbitrarily." It explicitly binds the prompt service project root to a specific project context. -如果不传，server 会按默认当前工作目录解释；如果传入，则会同时进入 `cwd` 与 `pluginOptions.workspaceDir`。 +If you do not pass it, the server resolves paths from the default current working directory. If you do pass it, the value is applied to both `cwd` and `pluginOptions.workspaceDir`. -## 使用边界 +## Usage Boundary -- 先保证 CLI 侧的项目结构是正确的，再接入 MCP -- MCP 只暴露当前已有的 prompt 管理行为，不替你发明新的 Schema -- 需要确认 prompt 类型与真源职责时，回看 [技术细节](/docs/technical-details) +- Make sure the CLI-side project structure is correct before integrating MCP +- MCP exposes only the prompt-management behavior that already exists and does not invent a new schema +- If you need to confirm prompt types and source-of-truth responsibilities, go back to [Technical Details](/docs/technical-details) diff --git a/doc/content/quick-guide/_meta.ts b/doc/content/quick-guide/_meta.ts index c1480a73..4963ba39 100644 --- a/doc/content/quick-guide/_meta.ts +++ b/doc/content/quick-guide/_meta.ts @@ -1,4 +1,4 @@ export default { - 'index': '概览', - 'quick-install': '快速安装' + 'index': 'Overview', + 'quick-install': 'Quick Install' } diff --git a/doc/content/quick-guide/index.mdx b/doc/content/quick-guide/index.mdx index 9f7c23a6..0c166228 100644 --- a/doc/content/quick-guide/index.mdx +++ b/doc/content/quick-guide/index.mdx @@ -1,7 +1,7 @@ --- -title: 快速指引 -description: 用最短路径判断应该从 CLI、GUI 还是 MCP 进入 memory-sync 文档。 -sidebarTitle: 概览 +title: Quick Guide +description: Decide whether to enter the memory-sync docs through CLI, GUI, or MCP using the shortest path. +sidebarTitle: Overview status: stable keywords: - memory-sync @@ -9,61 +9,61 @@ keywords: - onboarding --- -# 快速指引 +# Quick Guide -这一节不展开实现细节，只解决一件事：你现在应该先读哪条路径，才能最快进入可执行状态。 +This section does not dive into implementation details. It answers one question only: which path should you read first to get to a working state as quickly as possible? -## 架构速览 +## Architecture at a Glance ```mermaid flowchart LR; - Author["源内容作者"] --> CLI["CLI 终端同步入口"]; - Author --> GUI["GUI 桌面工作流入口"]; - Author --> Host["MCP Host 宿主"]; + Author["Source Author"] --> CLI["CLI Terminal Entry"]; + Author --> GUI["GUI Desktop Workflow Entry"]; + Author --> Host["MCP Host"]; CLI --> SDK["sdk private mixed core"]; GUI --> SDK; Host --> MCP["mcp stdio server"]; MCP --> SDK; - SDK --> Outputs["目标工具原生输出"]; + SDK --> Outputs["Native Outputs for Target Tools"]; ``` -这张图只强调当前 repo 的消费方向：`sdk/` 是单一核心层，`cli/`、`gui/`、`mcp/` 都围绕它工作，不是各自维护一套并行真源。 +This diagram highlights the current dependency direction only: `sdk/` is the single core layer, and `cli/`, `gui/`, and `mcp/` all work around it instead of maintaining parallel sources of truth. -## 先判断你的目标 +## Decide Your Goal First -| 你的目标 | 应该进入哪里 | 为什么 | +| Your Goal | Where to Go | Why | | --- | --- | --- | -| 在终端里同步 prompts、rules、skills、commands 或项目记忆 | [CLI](/docs/cli) | 当前真实操作入口、Schema、输出范围与清理边界都在这里核对 | -| 在桌面应用里编辑配置、触发执行、观察日志 | [GUI](/docs/gui) | `gui/` 负责桌面工作流，但核心执行仍然依赖 `sdk/` 中的 `tnmsc` crate | -| 把 `memory-sync-mcp` 接到支持 MCP 的宿主 | [MCP](/docs/mcp) | 这里单独说明 stdio server、工具清单与 `workspaceDir` 约束 | -| 先搞清 repo 内部架构分层，而不是马上使用 | [SDK](/docs/sdk) 与 [技术细节](/docs/technical-details) | 前者说明 mixed core 的边界，后者说明真源模型与同步管线 | +| Sync prompts, rules, skills, commands, or project memory from a terminal | [CLI](/docs/cli) | The real command surface, schema, output scopes, and cleanup boundaries are all verified there. | +| Edit config, trigger execution, and inspect logs from the desktop app | [GUI](/docs/gui) | `gui/` owns the desktop workflow, but execution still depends on the `tnmsc` crate in `sdk/`. | +| Connect `memory-sync-mcp` to an MCP-capable host | [MCP](/docs/mcp) | That section focuses on the stdio server, the tool list, and `workspaceDir` semantics. | +| Understand the repo architecture before using anything | [SDK](/docs/sdk) and [Technical Details](/docs/technical-details) | The first explains the mixed-core boundary, and the second explains the source-of-truth model and the sync pipeline. | -## 快速安装 +## Quick Install -如果你现在先想把命令装起来，再决定后面走 CLI、GUI 还是 MCP，直接看 [快速安装](/docs/quick-guide/quick-install)。 +If you want to install the command first and decide between CLI, GUI, and MCP later, go straight to [Quick Install](/docs/quick-guide/quick-install). -## 最短起步路径 +## Shortest Starting Paths -### 如果你走 CLI +### If You Start with CLI -1. 先看 [安装与前提](/docs/cli/install)。 -2. 再看 [项目与 aindex](/docs/cli/workspace-setup)。 -3. 然后用 [第一次同步](/docs/cli/first-sync) 跑通一次真实流程。 +1. Read [Installation and Requirements](/docs/cli/install). +2. Continue with [Workspace and aindex](/docs/cli/workspace-setup). +3. Then use [First Sync](/docs/cli/first-sync) to run through the real flow once. -### 如果你走 GUI +### If You Start with GUI -1. 先看 [GUI 概览](/docs/gui)。 -2. 再看 [页面与工作流](/docs/gui/workflows-and-pages)。 -3. 涉及命令、输出范围或清理边界时，回到 [CLI](/docs/cli) 核对事实。 +1. Read the [GUI Overview](/docs/gui). +2. Continue with [Workflows and Pages](/docs/gui/workflows-and-pages). +3. When command behavior, output scopes, or cleanup boundaries matter, go back to [CLI](/docs/cli) for the authoritative details. -### 如果你走 MCP +### If You Start with MCP -1. 先看 [MCP 概览](/docs/mcp)。 -2. 再看 [Server 与 Tools](/docs/mcp/server-tools)。 -3. 需要准备项目目录、理解 Schema 或输出边界时，回到 [CLI](/docs/cli)。 +1. Read the [MCP Overview](/docs/mcp). +2. Continue with [Server and Tools](/docs/mcp/server-tools). +3. If you need project setup, schema details, or output boundaries, go back to [CLI](/docs/cli). -## 进入前先记住三件事 +## Three Things to Remember Before You Dive In -- `sdk/` 是 repo 内部 mixed core，`cli/`、`mcp/`、`gui/` 都是消费者，不是平行真源。 -- 当前公开文档以仓库现状为准；如果旧页面、README 和代码冲突，以实际目录、命令表面和 Schema 为准。 -- 不确定入口时，优先从这页分流，而不是先翻实现细节。 +- `sdk/` is the internal mixed core of the repo. `cli/`, `mcp/`, and `gui/` are consumers, not parallel sources of truth. +- The public docs follow the current repository. If old pages, the README, and the code disagree, trust the actual directories, command surface, and schema. +- If you are unsure where to begin, use this page to branch first instead of opening implementation details at random. diff --git a/doc/content/quick-guide/quick-install.mdx b/doc/content/quick-guide/quick-install.mdx index 94e95f5e..81dbcdae 100644 --- a/doc/content/quick-guide/quick-install.mdx +++ b/doc/content/quick-guide/quick-install.mdx @@ -1,7 +1,7 @@ --- -title: 快速安装 -description: 用最短命令安装 memory-sync CLI，并确认你面对的是当前命令集。 -sidebarTitle: 快速安装 +title: Quick Install +description: Install the memory-sync CLI with the shortest possible commands and confirm that you are using the current command set. +sidebarTitle: Quick Install status: stable keywords: - quick install @@ -10,9 +10,9 @@ keywords: - cli --- -# 快速安装 +# Quick Install -如果你现在只想先把 CLI 装起来，按你常用的包管理器执行： +If you just want to get the CLI installed first, use your preferred package manager: -然后确认命令可用： +Then confirm that the command works: +Then confirm that the command works: ```sh tnmsc help ``` -你应该看到 `dry-run`、`clean` 与 `config`，同时看到 `init` 已经是 deprecated。 +You should see `dry-run`, `clean`, and `config`, and `init` should already be marked as deprecated. -## monorepo 本地开发 +## Local Monorepo Development -如果你是在这个 monorepo 里本地开发，改用： +If you are developing inside this monorepo, use: ```sh pnpm install @@ -40,10 +41,10 @@ pnpm -C cli exec node dist/index.mjs --help ``` > [!warning] -> 目前仅推荐使用 pnpm 进行开发 +> `pnpm` is the only recommended package manager for local development right now. -## 装完后下一步 +## What to Read Next -- 只想先跑一次真实流程，继续看 [第一次同步](/docs/cli/first-sync)。 -- 还没确认 Node、pnpm、Rust 的版本要求，继续看 [安装与前提](/docs/cli/install)。 -- 还没决定该走 CLI、GUI 还是 MCP，回到 [快速指引](/docs/quick-guide)。 +- If you want to run through the real flow once, continue with [First Sync](/docs/cli/first-sync). +- If you still need the Node, pnpm, and Rust version requirements, continue with [Installation and Requirements](/docs/cli/install). +- If you still have not decided between CLI, GUI, and MCP, go back to the [Quick Guide](/docs/quick-guide). diff --git a/doc/content/sdk/_meta.ts b/doc/content/sdk/_meta.ts index 01d60bc6..0b4d35fc 100644 --- a/doc/content/sdk/_meta.ts +++ b/doc/content/sdk/_meta.ts @@ -1,3 +1,3 @@ export default { - index: '概览' + index: 'Overview' } diff --git a/doc/content/sdk/index.mdx b/doc/content/sdk/index.mdx index 39744afb..0dc8911c 100644 --- a/doc/content/sdk/index.mdx +++ b/doc/content/sdk/index.mdx @@ -1,56 +1,56 @@ --- title: SDK -description: 说明 sdk/ 作为 private mixed core 的职责、边界、消费方向与对外身份保持策略。 -sidebarTitle: 概览 +description: Explains the responsibilities, boundaries, consumers, and public-identity strategy of sdk/ as the private mixed core. +sidebarTitle: Overview status: stable --- # SDK -`sdk/` 是当前仓库里的 private mixed core，也是 repo 内部共享能力的单一入口。它不是一个“给外部用户单独安装的 npm 包”，而是把原先放在 `cli/` 里的核心实现收拢后的真源层。 +`sdk/` is the private mixed core in the current repository and the single entrypoint for shared internal capability. It is not a standalone npm package meant for direct external installation. It is the source-of-truth layer created by pulling the old core implementation out of `cli/`. -## 这层负责什么 +## What This Layer Owns -- 承载私有 npm 包 `@truenine/memory-sync-sdk` -- 承载 Rust crate `tnmsc` 的实际工作区路径 -- 持有 TypeScript 同步管线、prompt service、schema 生成与 `plugin-runtime` -- 持有 Rust library、NAPI 构建、Node bridge runtime 与嵌入式运行时逻辑 -- 作为 `mcp/`、`gui/` 以及未来 repo 内部消费者的默认依赖点 +- It contains the private npm package `@truenine/memory-sync-sdk` +- It contains the actual workspace path for the Rust crate `tnmsc` +- It owns the TypeScript sync pipeline, prompt service, schema generation, and `plugin-runtime` +- It owns the Rust library, NAPI build, Node bridge runtime, and embedded runtime logic +- It is the default dependency point for `mcp/`, `gui/`, and future internal consumers -## 这层不负责什么 +## What This Layer Does Not Own -- 不直接承担公开 npm CLI 的发布入口 -- 不承担平台 shim 包 `@truenine/memory-sync-cli-` 的分发身份 -- 不把 repo 内部共享 API 再挂回 `cli/` 做二次真源 +- It does not directly own the public npm CLI release entrypoint +- It does not own distribution identity for platform shim packages such as `@truenine/memory-sync-cli-` +- It does not push shared internal APIs back into `cli/` as a second source of truth -## 身份保持不变的部分 +## Public Identities That Stay the Same -这次分层调整没有改动这些公开身份： +This layering change did not alter these public identities: -- CLI binary 仍然是 `tnmsc` -- 公共 npm CLI 包仍然是 `@truenine/memory-sync-cli` -- 公共平台包仍然是 `@truenine/memory-sync-cli-` -- Rust crate 名仍然是 `tnmsc` +- The CLI binary is still `tnmsc` +- The public npm CLI package is still `@truenine/memory-sync-cli` +- The public platform package is still `@truenine/memory-sync-cli-` +- The Rust crate name is still `tnmsc` -变化的是“路径与所有权”，不是这些对外身份本身。 +What changed was path and ownership, not the external identities themselves. -## 消费方向 +## Consumer Direction -| 消费方 | 依赖方式 | +| Consumer | Dependency Style | | --- | --- | -| `cli/` | 作为 shell 与兼容层，薄封装 `sdk/` 导出的能力 | -| `mcp/` | 直接导入 `@truenine/memory-sync-sdk` 的 prompt service | -| `gui/src-tauri` | 继续依赖 crate `tnmsc`，但 crate 实际路径位于 `sdk/` | +| `cli/` | A shell and compatibility layer that thinly wraps capability exported from `sdk/` | +| `mcp/` | Imports the prompt service directly from `@truenine/memory-sync-sdk` | +| `gui/src-tauri` | Continues to depend on the crate `tnmsc`, whose actual path now lives under `sdk/` | -## 边界规则 +## Boundary Rules -- repo 内部新代码不应再把 `cli/` 当成默认共享 API 入口 -- `cli/` 只保留命令入口、兼容导出与发布打包职责 -- 需要解释实现边界时，先看 `sdk/`，再看 `cli/`、`mcp/` 或 `gui/` +- New internal repo code should no longer treat `cli/` as the default shared API entrypoint +- `cli/` keeps only the command entrypoint, compatibility exports, and release packaging duties +- When you need to explain implementation boundaries, start with `sdk/` before looking at `cli/`, `mcp/`, or `gui/` -## 推荐阅读 +## Recommended Reading -- [技术细节 / 架构边界](/docs/technical-details/architecture)：查看 `sdk/`、`cli/`、`mcp/`、`gui/` 的整体分层。 -- [CLI](/docs/cli)：查看公开命令入口、安装与兼容发布表面。 -- [MCP](/docs/mcp)：查看 `sdk` prompt service 如何被 stdio server 消费。 -- [GUI](/docs/gui)：查看桌面层如何调用 `sdk/` 中的 `tnmsc` crate。 +- [Technical Details / Architecture Boundaries](/docs/technical-details/architecture): see the full layering of `sdk/`, `cli/`, `mcp/`, and `gui/` +- [CLI](/docs/cli): see the public command entrypoint, installation path, and compatibility-facing release surface +- [MCP](/docs/mcp): see how the `sdk` prompt service is consumed by the stdio server +- [GUI](/docs/gui): see how the desktop layer calls the `tnmsc` crate in `sdk/` diff --git a/doc/content/technical-details/_meta.ts b/doc/content/technical-details/_meta.ts index 9e91cca0..f923edab 100644 --- a/doc/content/technical-details/_meta.ts +++ b/doc/content/technical-details/_meta.ts @@ -1,10 +1,10 @@ export default { - 'index': '概览', - 'architecture': '架构边界', - 'pipeline': '同步管线', - 'source-of-truth': '单一真源模型', - 'documentation-components': '文档组件', - 'global-and-workspace-prompts': '全局与项目 Prompt', + 'index': 'Overview', + 'architecture': 'Architecture Boundaries', + 'pipeline': 'Sync Pipeline', + 'source-of-truth': 'Single Source of Truth', + 'documentation-components': 'Documentation Components', + 'global-and-workspace-prompts': 'Global and Workspace Prompts', 'skills': 'Skills', 'commands': 'Commands', 'subagents': 'Sub-agents', diff --git a/doc/content/technical-details/architecture.mdx b/doc/content/technical-details/architecture.mdx index 719c0f99..9e4174c0 100644 --- a/doc/content/technical-details/architecture.mdx +++ b/doc/content/technical-details/architecture.mdx @@ -1,36 +1,36 @@ --- -title: 架构边界 -description: 说明 tnmsc、crate、npm 包、MCP 与 GUI 之间的职责边界。 -sidebarTitle: 架构边界 +title: Architecture Boundaries +description: Explains the responsibility boundaries between tnmsc, the crate, npm packages, MCP, and the GUI. +sidebarTitle: Architecture Boundaries status: stable --- -# 架构边界 +# Architecture Boundaries -当前仓库的核心方向不是“继续堆更多纯 TypeScript 兼容层”，而是： +The core direction of the repository is not "keep stacking more pure TypeScript compatibility layers." It is: -- `sdk/` 作为私有 mixed core -- `cli/` 作为公开入口与兼容发布层 -- Rust crate / NAPI 作为长期核心实现重心 -- TypeScript 主要负责接口暴露、配置装配、桥接运行时与声明描述 +- `sdk/` as the private mixed core +- `cli/` as the public entrypoint and compatibility release layer +- Rust crate / NAPI as the long-term center of core implementation +- TypeScript focused mainly on interface exposure, config assembly, bridge runtime logic, and declarations -## 组件分工 +## Component Responsibilities -| 组件 | 职责 | +| Component | Responsibility | | --- | --- | -| `sdk/` | `tnmsc` crate、Node bridge runtime、prompt service、schema 与 NAPI 真源 | -| `cli/` | `tnmsc` 命令入口、公开 npm CLI 包、兼容发布壳 | -| `mcp/` | MCP stdio server，复用 sdk prompt service | -| `gui/` | Tauri 桌面调用层与展示层 | -| `libraries/` | Rust-first / NAPI-first 基础库 | +| `sdk/` | Source of truth for the `tnmsc` crate, Node bridge runtime, prompt service, schema, and NAPI | +| `cli/` | `tnmsc` command entrypoint, public npm CLI package, and compatibility release shell | +| `mcp/` | MCP stdio server that reuses the sdk prompt service | +| `gui/` | Tauri desktop invocation and presentation layer | +| `libraries/` | Rust-first / NAPI-first foundational libraries | -## 关键边界 +## Key Boundaries -- GUI 不是核心实现中心 -- MCP 不是新的真源模型 -- CLI 不是 repo 内部共享 API 的默认依赖点 -- 文档站不是架构真相的唯一来源 +- GUI is not the center of core implementation +- MCP is not a new source-of-truth model +- CLI is not the default dependency point for shared internal APIs +- The docs site is not the only source of architectural truth -如果你需要看用户操作面，回到 [CLI](/docs/cli) 或 [GUI](/docs/gui)；这里只说明实现分层为什么这样划。 +If you need the user-facing operational surface, go back to [CLI](/docs/cli) or [GUI](/docs/gui). This page explains only why the implementation is split this way. -如果你需要专门看 `sdk/` 这层本身的职责、消费方向与身份保持策略，直接进入 [SDK](/docs/sdk)。 +If you need the responsibilities, consumer direction, and identity-preservation strategy of `sdk/` specifically, go straight to [SDK](/docs/sdk). diff --git a/doc/content/technical-details/commands.mdx b/doc/content/technical-details/commands.mdx index b87418df..9a2ed250 100644 --- a/doc/content/technical-details/commands.mdx +++ b/doc/content/technical-details/commands.mdx @@ -1,43 +1,43 @@ --- title: Commands -description: 介绍 commands 的职责，以及它们与 commandSeriesOptions 的关系。 +description: Introduces the role of commands and explains how they relate to commandSeriesOptions. sidebarTitle: Commands status: stable --- # Commands -## Commands 适合什么 +## What Commands Are Good For -Commands 适合那些： +Commands are a good fit for operations that: -- 会高频复用 -- 执行目标清晰 -- 适合短文本触发 +- are reused frequently +- have a clear execution goal +- are easy to trigger with short text -的操作入口。 +They work best as concise operation entrypoints. -典型例子包括“生成发布说明”“复查某类错误”“按某个格式整理上下文”等。 +Typical examples include generating release notes, rechecking a class of errors, or reshaping context into a specific format. -## 当前路径约定 +## Current Path Convention -默认输入路径： +Default input path: ```text commands/ ``` -默认输出路径： +Default output path: ```text dist/commands/ ``` -## `commandSeriesOptions` 是干什么的 +## What `commandSeriesOptions` Does -Schema 里 `commandSeriesOptions` 允许你： +The schema lets `commandSeriesOptions`: -- 设置 `includeSeriesPrefix` -- 按插件覆盖 `includeSeriesPrefix` 或 `seriesSeparator` +- set `includeSeriesPrefix` +- override `includeSeriesPrefix` or `seriesSeparator` per plugin -这说明 commands 不只是平铺输出，还能带有“系列化”命名规则。你可以把它理解成对同一命令簇的分组与命名控制，而不是单一文件名规则。 +That means commands are not just flat output files. They can also carry series-based naming rules. Think of it as grouping and naming control for a command family rather than a single-file naming rule. diff --git a/doc/content/technical-details/documentation-components.mdx b/doc/content/technical-details/documentation-components.mdx index 4be3500c..5a3ddd55 100644 --- a/doc/content/technical-details/documentation-components.mdx +++ b/doc/content/technical-details/documentation-components.mdx @@ -1,150 +1,150 @@ --- -title: 文档组件 -description: 为 MDX 提供可复用的能力矩阵、系统支持表、平台卡片与命令参考组件。 -sidebarTitle: 文档组件 +title: Documentation Components +description: Provides reusable capability matrices, system support tables, platform cards, and command-reference components for MDX. +sidebarTitle: Documentation Components status: stable --- -# 文档组件 +# Documentation Components -`doc/` 现在可以直接在 MDX 里使用一组文档组件，不必继续手写大段 Markdown 表格。它们已经通过 `doc/mdx-components.tsx` 全局注册，所以任意 `.mdx` 页面都能直接写 JSX 标签。 +`doc/` can now use a shared set of documentation components directly inside MDX instead of hand-writing large Markdown tables. They are registered globally through `doc/mdx-components.tsx`, so any `.mdx` page can use the JSX tags directly. -## 1. 多工具功能矩阵 +## 1. Multi-Tool Capability Matrix -## 2. 多系统支持矩阵 +## 2. Multi-System Support Matrix -## 3. 系统展示卡片 +## 3. Platform Cards -## 4. 技术栈命令参考 +## 4. Tech-Stack Command Reference -## 5. 包管理器安装切换 +## 5. Package-Manager Install Tabs -`PackageManagerTabs` 适合放在安装页，避免只给 `npm` 一种写法。它会用统一组件切换 `npm`、`pnpm`、`yarn` 三组命令。 +`PackageManagerTabs` works well on install pages so you do not hardcode only one `npm` example. It uses a shared component to switch between `npm`, `pnpm`, and `yarn`. -## 使用方式 +## Usage -在任意 MDX 页面中直接写： +Write this directly in any MDX page: ```tsx @@ -166,9 +166,9 @@ status: stable ``` -如果后面还要继续扩展，建议沿着这个方向做，而不是回到散乱的原生 Markdown 表格： +If you extend this system later, keep moving in this direction instead of falling back to scattered raw Markdown tables: -- 表格类信息继续复用 `FeatureMatrix`、`SupportMatrix`、`CommandReference` -- 偏展示型内容复用 `PlatformGrid` -- 安装命令切换复用 `PackageManagerTabs` -- 需要完全自由布局时，再单独加新的卡片或对比组件 +- Reuse `FeatureMatrix`, `SupportMatrix`, and `CommandReference` for tabular information +- Reuse `PlatformGrid` for presentation-heavy content +- Reuse `PackageManagerTabs` for installation command switches +- Add new card or comparison components only when you truly need a freer layout diff --git a/doc/content/technical-details/global-and-workspace-prompts.mdx b/doc/content/technical-details/global-and-workspace-prompts.mdx index f32536b2..65f9c5df 100644 --- a/doc/content/technical-details/global-and-workspace-prompts.mdx +++ b/doc/content/technical-details/global-and-workspace-prompts.mdx @@ -1,46 +1,46 @@ --- -title: 全局与项目 Prompt -description: 说明 globalPrompt 与 workspacePrompt 的路径职责和适用范围。 -sidebarTitle: 全局与项目 Prompt +title: Global and Workspace Prompts +description: Explains the path responsibilities and usage boundaries of globalPrompt and workspacePrompt. +sidebarTitle: Global and Workspace Prompts status: stable --- -# 全局与项目 Prompt +# Global and Workspace Prompts -## 默认路径 +## Default Paths -当前默认配置中，这两份源文件分别是： +In the current default configuration, these two source files are: ```text global.src.mdx workspace.src.mdx ``` -输出目标默认是： +Their default output targets are: ```text dist/global.mdx dist/workspace.mdx ``` -## 它们的区别 +## How They Differ -- `globalPrompt` 面向跨项目长期记忆，适合个人工作风格、稳定偏好与跨仓库通用约束。 -- `workspacePrompt` 面向当前项目上下文，适合项目规则、架构限制、技术栈边界与交付约束。 +- `globalPrompt` is for long-lived cross-project memory, such as personal work style, stable preferences, and constraints shared across repositories. +- `workspacePrompt` is for the current project context, such as project rules, architecture limits, stack boundaries, and delivery constraints. -## 什么时候不要把内容写进 global +## When Not to Put Content into global -如果内容明显依赖某个仓库的： +If the content clearly depends on a repository's: -- 目录结构 -- 业务词汇 -- 交付边界 -- 团队约束 +- directory structure +- domain vocabulary +- delivery boundary +- team constraints -那就不该放到 `globalPrompt`。否则你只是把项目噪音扩散到了所有未来目标。 +then it does not belong in `globalPrompt`. Otherwise you are just spreading project-specific noise into every future target. -## 编写原则 +## Writing Principles -1. 能放项目 Prompt 的，不要抢着放 global。 -2. 不要把目标工具特有路径和格式硬编码进真源。 -3. 如果某段内容本质上更像可复用卡片，应优先考虑抽成 skill 或 rule，而不是继续把 Prompt 膨胀成一整面墙。 +1. If something can live in a workspace prompt, do not rush to put it in global. +2. Do not hardcode target-tool-specific paths or formats into the source of truth. +3. If a block of content is really a reusable card, prefer extracting it into a skill or rule instead of growing the prompt into a wall of text. diff --git a/doc/content/technical-details/index.mdx b/doc/content/technical-details/index.mdx index f381bf8c..a9faee86 100644 --- a/doc/content/technical-details/index.mdx +++ b/doc/content/technical-details/index.mdx @@ -1,27 +1,27 @@ --- -title: 技术细节 -description: 集中说明架构边界、同步管线、真源模型与各类输入资产的实现职责。 -sidebarTitle: 概览 +title: Technical Details +description: Explains architecture boundaries, the sync pipeline, the source-of-truth model, and the implementation role of each input asset. +sidebarTitle: Overview status: stable --- -# 技术细节 +# Technical Details -这一节不讲“第一次怎么用”，而是讲当前实现为什么这样分层，以及 prompts、skills、commands、sub-agents、rules 这些输入资产在系统里分别扮演什么角色。 +This section does not explain first-time usage. It explains why the current implementation is layered this way and what role prompts, skills, commands, sub-agents, and rules each play inside the system. -## 这一节回答什么问题 +## Questions This Section Answers -1. 哪些东西是真源，哪些只是派生输出。 -2. 为什么仓库明确转向 Rust-first / NAPI-first。 -3. 同步为什么必须显式建模写入目标、输出范围和清理边界。 -4. 各类输入资产为什么不能混写成一坨大 Prompt。 +1. Which things are sources of truth, and which are only derived outputs. +2. Why the repository has clearly moved toward Rust-first / NAPI-first. +3. Why sync must model output targets, output scopes, and cleanup boundaries explicitly. +4. Why different input assets should not be collapsed into one giant prompt. -## 推荐阅读 +## Recommended Reading -- [架构边界](/docs/technical-details/architecture) -- [单一真源模型](/docs/technical-details/source-of-truth) -- [同步管线](/docs/technical-details/pipeline) -- [全局与项目 Prompt](/docs/technical-details/global-and-workspace-prompts) +- [Architecture Boundaries](/docs/technical-details/architecture) +- [Single Source of Truth](/docs/technical-details/source-of-truth) +- [Sync Pipeline](/docs/technical-details/pipeline) +- [Global and Workspace Prompts](/docs/technical-details/global-and-workspace-prompts) - [Skills](/docs/technical-details/skills) - [Commands](/docs/technical-details/commands) - [Sub-agents](/docs/technical-details/subagents) diff --git a/doc/content/technical-details/libraries.mdx b/doc/content/technical-details/libraries.mdx index c1669119..bc19f761 100644 --- a/doc/content/technical-details/libraries.mdx +++ b/doc/content/technical-details/libraries.mdx @@ -1,26 +1,26 @@ --- title: Libraries -description: 汇总当前 libraries/ 中几个 Rust-first / NAPI-first 基础库的职责与暴露形态。 +description: Summarizes the responsibilities and exposed surfaces of the Rust-first / NAPI-first foundational libraries currently under libraries/. sidebarTitle: Libraries status: stable --- # Libraries -`libraries/` 是 Rust-first / NAPI-first 的基础库目录。当前可见的重点库包括： +`libraries/` is the directory for Rust-first / NAPI-first foundational libraries. The main visible libraries right now are: - `logger` - `md-compiler` - `script-runtime` -## 各自的大致职责 +## Rough Responsibility of Each One -| 库 | 作用 | +| Library | Role | | --- | --- | -| `logger` | 日志能力，既有 Rust 实现，也有 TypeScript-facing 接口与 NAPI 产物 | -| `md-compiler` | MDX / Markdown 相关编译与转换能力 | -| `script-runtime` | 脚本运行时相关基础能力，供上层装配使用 | +| `logger` | Logging capability with Rust implementation plus TypeScript-facing APIs and NAPI artifacts | +| `md-compiler` | MDX / Markdown compilation and transformation capability | +| `script-runtime` | Foundational script-runtime capability consumed by higher-level assembly | -## 为什么它们值得单列 +## Why They Deserve Their Own Section -这些库不是“文档补充材料”，而是仓库长期把核心能力下沉为基础设施的证据。CLI、MCP 和 GUI 都应复用它们，而不是在各自目录里复制一套逻辑。 +These libraries are not "extra documentation material." They are evidence that the repository keeps pushing core capability down into shared infrastructure. CLI, MCP, and GUI should all reuse them rather than duplicating their own versions of the same logic. diff --git a/doc/content/technical-details/pipeline.mdx b/doc/content/technical-details/pipeline.mdx index c90dcb46..1ede1636 100644 --- a/doc/content/technical-details/pipeline.mdx +++ b/doc/content/technical-details/pipeline.mdx @@ -1,33 +1,33 @@ --- -title: 同步管线 -description: 说明插件如何声明目标文件、生成流程、输出范围与清理行为。 -sidebarTitle: 同步管线 +title: Sync Pipeline +description: Explains how plugins declare target files, generation flow, output scopes, and cleanup behavior. +sidebarTitle: Sync Pipeline status: stable --- -# 同步管线 +# Sync Pipeline -同步不是“把几份 Prompt 文本复制到几个目录里”，而是由插件声明目标文件、输出主题、清理范围与写入方式的管线。 +Sync is not "copy a few prompt files into a few directories." It is a pipeline where plugins declare target files, output topics, cleanup scopes, and write behavior. -## 管线最少包含什么 +## What the Pipeline Must Include at Minimum -- 读取真源输入资产 -- 合并项目与全局配置 -- 按插件决定输出目标 -- 应用 `outputScopes` 约束 -- 写入目标文件 -- 在需要时执行清理 +- Read source-of-truth input assets +- Merge project and global config +- Decide output targets per plugin +- Apply `outputScopes` +- Write target files +- Run cleanup when needed -## 为什么这件事必须显式建模 +## Why This Must Be Modeled Explicitly -如果不显式建模： +Without explicit modeling: -- 你无法知道哪些内容该写到全局，哪些只该写到项目级 -- 你无法在 `clean` 时给出可靠的删除边界 -- 你很容易把目标工具的偶然格式要求反向污染真源 +- You cannot know which content belongs in global outputs and which belongs only at the project level +- You cannot offer reliable deletion boundaries during `clean` +- You can easily let incidental formatting rules from target tools leak back into the source of truth -## 相关入口 +## Related Pages -- 配置字段行为：看 [CLI / JSON Schema](/docs/cli/schema) -- 输出范围控制：看 [CLI / 输出范围](/docs/cli/output-scopes) -- 真源与派生关系：看 [单一真源模型](/docs/technical-details/source-of-truth) +- Config-field behavior: see [CLI / JSON Schema](/docs/cli/schema) +- Output-scope control: see [CLI / Output Scopes](/docs/cli/output-scopes) +- Source-versus-derived relationship: see [Single Source of Truth](/docs/technical-details/source-of-truth) diff --git a/doc/content/technical-details/rules.mdx b/doc/content/technical-details/rules.mdx index 9eed9cc7..c770862e 100644 --- a/doc/content/technical-details/rules.mdx +++ b/doc/content/technical-details/rules.mdx @@ -1,39 +1,39 @@ --- title: Rules -description: 说明 rules 在项目级与全局级之间的作用，以及它们为何适合做持续约束。 +description: Explains how rules work at project and global scope, and why they fit ongoing constraints. sidebarTitle: Rules status: stable --- # Rules -## Rules 适合放什么 +## What Rules Are Good For -Rules 更适合表达持续性约束，例如： +Rules are better for long-lived constraints such as: -- 目录职责 -- 架构边界 -- 代码风格红线 -- 审查与交付纪律 +- directory responsibilities +- architecture boundaries +- code-style red lines +- review and delivery discipline -它们比 command 更稳定，比 skill 更偏约束而非能力。 +They are more stable than commands and more constraint-oriented than skills. -## 当前路径约定 +## Current Path Convention -默认输入路径： +Default input path: ```text rules/ ``` -默认输出路径： +Default output path: ```text dist/rules/ ``` -## Rules 和 output scopes 的关系 +## How Rules Relate to output scopes -Schema 允许你对 `rules` 单独设置 `project` 或 `global` 输出范围，这一点很关键。因为某些工具需要全局规则，而另一些规则只应留在当前项目。 +The schema lets you assign `rules` their own `project` or `global` output scope, and that matters a lot. Some tools need global rules, while others should only receive project-local rules. -如果你发现规则被写到了不该出现的地方，不要先怀疑 rule 文件本身，先看 [CLI / 输出范围](/docs/cli/output-scopes)。 +If rules are written where they do not belong, do not blame the rule file first. Check [CLI / Output Scopes](/docs/cli/output-scopes) first. diff --git a/doc/content/technical-details/skills.mdx b/doc/content/technical-details/skills.mdx index d8b8c1f7..506e90a2 100644 --- a/doc/content/technical-details/skills.mdx +++ b/doc/content/technical-details/skills.mdx @@ -1,44 +1,44 @@ --- title: Skills -description: 介绍 skills 作为可复用能力卡片的定位，以及它们与输出插件之间的关系。 +description: Introduces skills as reusable capability cards and explains how they relate to output plugins. sidebarTitle: Skills status: stable --- # Skills -## Skills 是什么 +## What Skills Are -Skills 是按任务主题切分的可复用能力卡片。它们适合表达： +Skills are reusable capability cards split by task theme. They are a good fit for expressing: -- 某类交付物的写法 -- 某种架构决策的方法 -- 某个操作流程的步骤化知识 +- how to produce a certain type of deliverable +- a method for making a certain type of architectural decision +- step-by-step knowledge for a specific operational flow -## 当前路径约定 +## Current Path Convention -默认输入路径是： +The default input path is: ```text skills/ ``` -默认导出路径是： +The default export path is: ```text dist/skills/ ``` -## 为什么它们和 Prompt 不一样 +## Why They Are Not the Same as Prompts -Prompt 更像持续上下文，Skills 更像按需调用的模块。两者都能影响模型行为，但不是一个抽象层。 +Prompts behave more like persistent context, while skills behave more like on-demand modules. Both can influence model behavior, but they are not the same abstraction layer. -## 输出层会关心什么 +## What the Output Layer Cares About -`tnmsc` 现在默认把 skill 目录名当作 skill name。 +`tnmsc` now uses the skill directory name as the skill name by default. -- 不需要在 skill frontmatter 里写 `name` -- 如果写了 `name`，同步时会忽略并给出告警 -- 想修改 skill name，直接修改 `skills//` 的目录名 +- You do not need to put `name` in skill frontmatter +- If you do add `name`, sync ignores it and emits a warning +- If you want to change the skill name, rename `skills//` -详细字段说明见 [CLI / Front Matter](/docs/cli/frontmatter)。 +See [CLI / Front Matter](/docs/cli/frontmatter) for field details. diff --git a/doc/content/technical-details/source-of-truth.mdx b/doc/content/technical-details/source-of-truth.mdx index 088cfcb9..248666ab 100644 --- a/doc/content/technical-details/source-of-truth.mdx +++ b/doc/content/technical-details/source-of-truth.mdx @@ -1,34 +1,34 @@ --- -title: 单一真源模型 -description: 解释 .src.mdx、源目录与目标工具产物之间的关系，以及为什么输出文件不应被当作真源维护。 -sidebarTitle: 单一真源模型 +title: Single Source of Truth +description: Explains the relationship between .src.mdx, source directories, and target-tool outputs, and why output files should not be maintained as the source of truth. +sidebarTitle: Single Source of Truth status: stable --- -# 单一真源模型 +# Single Source of Truth -`memory-sync` 的关键前提是：真源应该是你维护的输入资产，而不是目标工具最终读到的派生文件。 +The key premise of `memory-sync` is this: the source of truth should be the input assets you maintain, not the derived files consumed by target tools. -## 哪些通常是真源 +## What Is Usually Source of Truth -- 全局 Prompt -- 项目 Prompt +- Global prompts +- Workspace prompts - `skills/` - `commands/` - `subagents/` - `rules/` -## 哪些通常不是 +## What Usually Is Not -- 各种工具原生配置落点 -- 导出的 dist 内容 -- 桌面层展示状态 -- MCP 返回的读取结果 +- Native config destinations for different tools +- Exported dist content +- Desktop-layer display state +- Data returned by MCP reads -## 为什么不能把输出文件当真源 +## Why Output Files Cannot Be the Source of Truth -因为输出文件会天然带上目标工具的路径、命名、格式和能力限制。一旦把它们当真源，迁移成本和清理复杂度都会急剧上升。 +Because output files naturally carry the path, naming, formatting, and capability constraints of their target tools. Once you treat those as the source of truth, migration cost and cleanup complexity both rise sharply. -## 实操含义 +## Practical Meaning -需要调整行为时，优先改真源和配置，而不是去目标工具目录里热修一份派生文件。 +When behavior needs to change, modify the source-of-truth inputs and config first instead of hot-fixing a derived file inside a target-tool directory. diff --git a/doc/content/technical-details/subagents.mdx b/doc/content/technical-details/subagents.mdx index ea651be3..9d6d2b59 100644 --- a/doc/content/technical-details/subagents.mdx +++ b/doc/content/technical-details/subagents.mdx @@ -1,45 +1,45 @@ --- title: Sub-agents -description: 说明 sub-agents 在 memory-sync 中的输入定位以及命名约束。 +description: Explains the role of sub-agents as input assets in memory-sync and the naming constraints around them. sidebarTitle: Sub-agents status: stable --- # Sub-agents -## Sub-agents 的角色 +## The Role of Sub-agents -Sub-agents 用于把复杂任务拆成更专门的角色和边界。它们不是普通 Prompt 复制品，而是更接近“受约束的专职执行单元”。 +Sub-agents split complex work into more specialized roles and boundaries. They are not copies of a normal prompt. They are closer to constrained specialist execution units. -## 当前路径约定 +## Current Path Convention -默认输入路径： +Default input path: ```text subagents/ ``` -默认输出路径： +Default output path: ```text dist/subagents/ ``` -## 命名为什么重要 +## Why Naming Matters -`tnmsc` 现在默认从 sub-agent 的相对路径推导名称： +`tnmsc` now derives the sub-agent name from its relative path by default: - `subagents/reviewer.src.mdx` -> `reviewer` - `subagents/qa/boot.src.mdx` -> `qa-boot` -因此： +That means: -- 不需要在 frontmatter 里写 `name` -- 如果写了 `name`，同步时会忽略并给出告警 -- 想修改 sub-agent name，直接修改目录名或文件名 +- You do not need to put `name` in frontmatter +- If you do add `name`, sync ignores it and emits a warning +- If you want to change the sub-agent name, rename the directory or filename -## 什么时候该写成 sub-agent，而不是 skill +## When It Should Be a Sub-agent Instead of a Skill -- 你需要一个长期存在、职责边界明确的角色。 -- 这个角色可能需要独立描述输入、行为约束与输出形式。 -- 它不仅是“做一件事的方法”，而是“承担一类工作的代理配置”。 +- You need a long-lived role with a clear responsibility boundary. +- That role needs its own description of inputs, behavior constraints, and output shape. +- It is not just a method for doing one thing. It is an agent configuration for owning a class of work. diff --git a/doc/lib/docs-sections.ts b/doc/lib/docs-sections.ts index de9b4971..09feb97c 100644 --- a/doc/lib/docs-sections.ts +++ b/doc/lib/docs-sections.ts @@ -1,17 +1,17 @@ export const DOC_SECTION_LINKS = [ - {href: '/docs/quick-guide', label: '快速指引', section: 'quick-guide'}, + {href: '/docs/quick-guide', label: 'Quick Guide', section: 'quick-guide'}, {href: '/docs/cli', label: 'CLI', section: 'cli'}, {href: '/docs/sdk', label: 'SDK', section: 'sdk'}, {href: '/docs/mcp', label: 'MCP', section: 'mcp'}, {href: '/docs/gui', label: 'GUI', section: 'gui'}, { href: '/docs/technical-details', - label: '技术细节', + label: 'Technical Details', section: 'technical-details' }, { href: '/docs/design-rationale', - label: '设计初衷', + label: 'Design Rationale', section: 'design-rationale' } ] as const diff --git a/doc/lib/site.ts b/doc/lib/site.ts index db4a3670..19769e95 100644 --- a/doc/lib/site.ts +++ b/doc/lib/site.ts @@ -3,9 +3,9 @@ import process from 'node:process' export const siteConfig = { productName: 'memory-sync', shortName: 'memory-sync Docs', - title: 'memory-sync 文档', + title: 'memory-sync Docs', description: - '面向多 AI 工具的 prompt、rule、skill、command 与 project memory sync 文档站。', + 'Documentation for memory-sync: prompts, rules, skills, commands, and project memory sync across multiple AI tools.', repoUrl: 'https://github.com/TrueNine/memory-sync', docsRepositoryBase: 'https://github.com/TrueNine/memory-sync/blob/main/doc', issueUrl: 'https://github.com/TrueNine/memory-sync/issues/new/choose' @@ -33,62 +33,62 @@ export const heroProofPoints = [ export const homeEntryCards = [ { href: '/docs/quick-guide', - title: '快速指引', - detail: '先用一页判断你应该从 CLI、GUI 还是 MCP 进入，再跳到最短可执行路径。' + title: 'Quick Guide', + detail: 'Decide whether to start with CLI, GUI, or MCP from a single page, then jump to the shortest workable path.' }, { href: '/docs/cli', title: 'CLI', - detail: '围绕安装、项目准备、第一次同步、配置字段与命令表面组织。' + detail: 'Organized around installation, project setup, the first sync run, configuration fields, and the exposed command surface.' }, { href: '/docs/sdk', title: 'SDK', - detail: '单独说明 private mixed core 的职责边界、消费方向，以及它与 tnmsc crate / cli shell 的关系。' + detail: 'Explains the private mixed core, its ownership boundaries, its consumers, and how it relates to the tnmsc crate and CLI shell.' }, { href: '/docs/mcp', title: 'MCP', - detail: '独立查看 stdio server、工具列表、workspaceDir 约束与适用边界。' + detail: 'Covers the stdio server, the exposed tools, workspaceDir semantics, and the integration boundary.' }, { href: '/docs/gui', title: 'GUI', - detail: '单独查看桌面层的职责、页面结构，以及它与 sdk / tnmsc crate / CLI 的关系。' + detail: 'Focuses on the desktop layer, its page structure, and how it works with sdk, the tnmsc crate, and the CLI.' }, { href: '/docs/technical-details', - title: '技术细节', - detail: '集中阅读架构边界、同步管线、真源模型与内容编写约定。' + title: 'Technical Details', + detail: 'Concentrates the architecture boundaries, the sync pipeline, the source-of-truth model, and authoring conventions.' }, { href: '/docs/design-rationale', - title: '设计初衷', - detail: '把项目动机、设计理由与 manifesto 类内容单独收口，不再混入使用文档。' + title: 'Design Rationale', + detail: 'Keeps project motivation, design reasoning, and manifesto-style content separate from usage docs.' } ] as const export const capabilityCards = [ { label: 'Prompt Source', - title: '统一维护输入资产', + title: 'Maintain Input Assets in One Place', detail: - '用 `.src.mdx` 和结构化 front matter 维护 prompt、skill、command、sub-agent 与 rule。' + 'Use `.src.mdx` files and structured front matter to maintain prompts, skills, commands, sub-agents, and rules.' }, { label: 'Pipeline', - title: '按目标工具生成原生输出', - detail: '由插件声明写入目标、清理范围与生成策略，避免手工复制配置。' + title: 'Materialize Native Outputs Per Tool', + detail: 'Let plugins declare output targets, cleanup scopes, and generation strategy instead of copying config by hand.' }, { label: 'Protection', - title: '显式控制删除边界', - detail: '`cleanupProtection` 与 `outputScopes` 用于约束清理范围和风险边界。' + title: 'Control Deletion Boundaries Explicitly', + detail: '`cleanupProtection` and `outputScopes` define cleanup scope and risk boundaries.' }, { label: 'Docs', - title: '文档只记录仓库已存在能力', - detail: '页面内容对齐当前实现、CLI 帮助、Schema 与工作流事实，不延续旧叙事。' + title: 'Document Only What the Repo Actually Does', + detail: 'Pages stay aligned with the current implementation, CLI help, schema, and workflow behavior instead of carrying old narratives forward.' } ] as const @@ -96,31 +96,31 @@ export const readingPath = [ { step: '01', href: '/docs/quick-guide', - title: '选择入口', - description: '先判断你当前是终端同步、桌面工作流还是 MCP 集成。' + title: 'Choose Your Entry Point', + description: 'Decide whether you are starting from terminal sync, the desktop workflow, or MCP integration.' }, { step: '02', href: '/docs/cli/install', - title: '确认运行前提', - description: '先核对 Node、Rust、CLI 入口与当前支持边界。' + title: 'Confirm Runtime Requirements', + description: 'Verify Node, Rust, the CLI entrypoint, and the currently supported boundaries first.' }, { step: '03', href: '/docs/cli/workspace-setup', - title: '准备项目结构', - description: '按照 aindex 与项目配置的真实目录约定组织源文件。' + title: 'Prepare the Project Structure', + description: 'Organize source files around the actual aindex and project-config directory conventions.' }, { step: '04', href: '/docs/technical-details/source-of-truth', - title: '开始维护源内容', - description: '先建立真源模型，再区分全局 Prompt、项目 Prompt 与其他输入资产。' + title: 'Start Maintaining Source Content', + description: 'Establish the source-of-truth model first, then separate global prompts, workspace prompts, and other input assets.' }, { step: '05', href: '/docs/cli/cli-commands', - title: '执行 dry-run 与同步', - description: '在写入目标工具前先验证输出列表、范围与清理行为。' + title: 'Run dry-run and Sync', + description: 'Validate the output list, scope, and cleanup behavior before writing into target tools.' } ] as const diff --git a/libraries/md-compiler/src/compiler/jsx-expression-eval.ts b/libraries/md-compiler/src/compiler/jsx-expression-eval.ts index 8a0602a3..182d6070 100644 --- a/libraries/md-compiler/src/compiler/jsx-expression-eval.ts +++ b/libraries/md-compiler/src/compiler/jsx-expression-eval.ts @@ -7,7 +7,7 @@ import type { JSXSpreadChild, JSXText } from 'estree-jsx' -import type {RootContent} from 'mdast' +import type {Root, RootContent} from 'mdast' import type {MdxFlowExpression, MdxJsxFlowElement, MdxTextExpression} from 'mdast-util-mdx' import type {EvaluateExpressionOptions} from './expression-eval' import type {ProcessingContext} from './types' @@ -246,8 +246,10 @@ async function processJsxElement( const mdxElement = convertEstreeJsxToMdx(jsxElement, ctx) if (mdxElement.name != null && isMdxComponent(mdxElement.name, ctx)) { - const {processAst} = await import('./transformer') - return processComponent(mdxElement, ctx, processAst) + return processComponent(mdxElement, ctx, async (ast: Root, c: ProcessingContext) => ({ + type: 'root', + children: await processAstFn(ast.children, c) + })) } const converted = convertJsxToMarkdown(mdxElement, ctx)