工作区与技能

工作区是助理每次对话都会读取的文件夹：你的指令、你的画像、你的私有技能，以及允许它放文件的位置。全新安装会搭好 ~/workspace；本页说明里面有什么，以及日后如何修复或对齐。

初始化

xiaohe workspace init

重复执行是安全的：已有文件永远不会被覆盖。它会把工作区路径写入本机设置、创建骨架、复制指令模板，并装好各 harness 的入口别名。

它创建的内容：

路径	用途
AGENTS.md	每个助理都要读的指令（Codex、Claude、Hermes）
PERSONAL.md	你的画像：姓名、称呼、联系方式、偏好
CLAUDE.md、.hermes.md	指向 AGENTS.md 的别名
.claude → .agents	目录别名；.agents/skills/ 放私有技能
assistant/	logs/、checkpoints/、knowledge/、pending/、prompts/
local/、share/、scripts/	项目链接、交付物与辅助脚本
tmp/	下载、截图、导出的临时空间

在 Windows 上，创建符号链接需要一次管理员授权。若点了拒绝，别名会退化为副本；之后运行 xiaohe workspace link 可以再转回来。

填写 PERSONAL.md

AGENTS.md 会引入 PERSONAL.md，但 init 只复制了示例。打开 ~/workspace/PERSONAL.md，把占位内容换成你自己的：

• 姓名与希望被怎样称呼；
• 身份、单位、联系方式；
• 沟通与代码偏好；
• 交付物放哪里；
• 可选的固定知识库入口。

在此之前，xiaohe doctor 会报告该文件仍是模板占位。那是警告，不是安装坏了。

技能

技能不会被复制进工作区。它分两层：

层	在哪里	怎么列出
社区版	随运行时一起发布	xiaohe skills list --tier community
目录版（Pro）	由 Hub 按需下发	xiaohe skills list --tier catalog
工作区	<workspace>/.agents/skills/	xiaohe skills list --tier workspace

.agents/skills/ 为空是正常的：它只放私有或项目专属技能。直接问助理“你有哪些技能”也可以 —— 列出的就是同一个目录。

目录版技能的 references/ 文件不在本地磁盘上；助理经由 Hub 按需获取。不要把 ~/.xiaohe/hub-cache 复制进工作区。

健康检查

xiaohe doctor

它检查工作区路径、指令别名、PERSONAL.md（缺失或仍是占位）以及必需的文件夹。缺项通常意味着初始化做了一半；重跑 xiaohe workspace init 即可修复。

升级后保持对齐

工作区与产品模板相互独立。升级不会改写你的 AGENTS.md。

xiaohe workspace diff       # 只读对比
xiaohe workspace baseline   # 记录已审阅的锚点

审阅差异，只合并适用于你的部分；不要整文件替换。workspace-align 技能会带着你做这场语义审改。

xiaohe workspace diff 会报告 aligned、product-forward、local-change、both-changed、personalized、no-baseline 之一。首次全新初始化会自动记录锚点。

排错

现象	可以试试
缺少 PERSONAL.md	重跑 xiaohe workspace init
doctor 报 PERSONAL.md still has template placeholders	自己填；init 写不了你的画像
local/、share/ 或 scripts/ 缺失	重跑 xiaohe workspace init
.agents/skills/ 是空的	正常；技能来自运行时和 Hub
workspace diff 报 no-baseline	审阅差异，然后运行 xiaohe workspace baseline
你的 AGENTS.md 没有更新	符合预期；用 workspace diff 做语义审改
Windows 上别名是副本而不是链接	运行 xiaohe workspace link 并通过 UAC 提示