Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/actions/setup-node-pnpm/action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }}

Expand Down
2 changes: 1 addition & 1 deletion doc/components/package-manager-tabs.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ export function PackageManagerTabs({
>
{tab.label}
{tab.id === recommendedManager
? <span className="docs-package-manager-tab-badge">推荐</span>
? <span className="docs-package-manager-tab-badge">Recommended</span>
: null}
</button>
)
Expand Down
8 changes: 4 additions & 4 deletions doc/content/_meta.ts
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
export default {
'index': {
title: '文档总览'
title: 'Overview'
},
'quick-guide': {
title: '快速指引'
title: 'Quick Guide'
},
'cli': {
title: 'CLI'
Expand All @@ -18,9 +18,9 @@ export default {
title: 'GUI'
},
'technical-details': {
title: '技术细节'
title: 'Technical Details'
},
'design-rationale': {
title: '设计初衷'
title: 'Design Rationale'
}
}
24 changes: 12 additions & 12 deletions doc/content/cli/_meta.ts
Original file line number Diff line number Diff line change
@@ -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'
}
46 changes: 23 additions & 23 deletions doc/content/cli/cleanup-protection.mdx
Original file line number Diff line number Diff line change
@@ -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
{
Expand All @@ -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"
}
]
}
Expand Down
52 changes: 26 additions & 26 deletions doc/content/cli/cli-commands.mdx
Original file line number Diff line number Diff line change
@@ -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`
Expand All @@ -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.
42 changes: 21 additions & 21 deletions doc/content/cli/dry-run-and-clean.mdx
Original file line number Diff line number Diff line change
@@ -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).
32 changes: 16 additions & 16 deletions doc/content/cli/first-sync.mdx
Original file line number Diff line number Diff line change
@@ -1,34 +1,34 @@
---
title: 第一次同步
description: 按最短路径完成 tnmsc helpdry-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
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)
Loading
Loading