Imported from LeonYoah/stx-website (
AGENTS.md). Install upstream withnpx skills add LeonYoah/stx-website. Copyright stays with the author.
AGENTS.md
面向本仓库（STX 官网 / 文档站）的写作与协作约定。写文档、改侧栏、改首页时先读这里，避免写偏。
对作者（Agent）的要求
- 先读源码与上游文档，再动笔。 权威在
/Users/mac/Documents/projects/stx（及同仓docs/、注释、config.example.yaml、agent.proto等）。官网文档可以对齐行为与默认值，但不要把源码考古过程写进用户文案。 - 写给用户看，不是写给同事看。 禁止元叙述（如「本文按源码整理」「不写已退役链路」）、禁止塞 legacy / 命令壳 / 错误码 / 内部函数名 / 原始 API 清单当正文。
- 不要替产品下结论。 用户没说的「生产更推荐…」等倾向性表述不要写；能力边界按现状如实说（例如 Docker/K8s 作被纳管主机类型尚未适配）。
- 抽象概念必须举例。 角色、网络、
app.external_url等用具体 IP / 机器名说明对错写法。 - 默认值与连通性写清楚。 端口、心跳、安装命令里会带出的地址等，该写就写（如
stx-java-proxy默认 18080，须与 STX Server 打通）。 - 图要真能渲染。 Mermaid 依赖
@docusaurus/theme-mermaid+markdown.mermaid: true；改完在站点里确认，不要只看编辑器 Markdown 预览。 - 讲 Web UI 操作时配截图。 列表页、关键入口、状态列等单靠文字不够；图放
static/img/screenshots/，文中用/img/screenshots/…。没有现成图就先向用户要，不要空写「见某某页」。 - 信息架构：首页是官网落地页；文档区侧栏竖排。 侧栏分类用纯文字，不加 emoji 小图标。
对文章的要求
| 要 | 不要 |
|---|---|
| 有细节、可操作（步骤、端口、约束） | 啰嗦、堆术语、堆实现细节 |
| 中文用户能直接读懂 | bare_metal、sidecar、Control Plane、Online 等黑话当主文案 |
| 术语前后统一 | 同一概念多种叫法混用 |
推荐用语
| 概念 | 写法 |
|---|---|
| 网页界面 | Web UI（不要叫「控制台」） |
| 跑 STX Server / Web UI 的机器 | STX 安装机 |
| 「主机管理」里登记、跑探针的机器 | 被纳管主机 |
| 边上的探针进程 | stx-agent（不要笼统叫 Agent，以免和 AI Agent 混淆） |
| 主机类型（当前可用） | 物理机 / 虚拟机（不要写 bare_metal） |
| 后端进程 | STX Server（可附 stx api） |
| 节点上的 Java 辅助进程 | stx-java-proxy（说「辅助进程 / 独立进程」，不要 sidecar） |
| 部署模式 | 混合 / 分离（CLI 示例里保留真实参数即可） |
| 大模型侧智能体 | AI Agent（与 stx-agent 区分开） |
产品叙事（CLI）
写 CLI / 智能运维相关文档时，先讲清：
- 原生支持 CLI，是因为 AI Agent 时代与系统打通的最佳范式是命令行——模型操作 CLI 远比操浏览器或直接调接口方便。人用 CLI 做脚本 / CI，模型用同一套
stx命令；不要写成「顺便做了个命令行工具」。 - 审计要放在 CLI 语境里写：专门优化审计 / 命令日志，是为了让每次 CLI 调用有迹可循（
client_type=cli、request_id可串到 stx-agent 命令），防止 AI 错误调用后排查不到问题。
文档结构习惯
- 中文默认内容在
docs/；侧栏在sidebars.ts；英文标签在i18n/en/.../current.json。 - 主机 / 集群类文档放在
docs/host-cluster/，侧栏「主机与集群管理」下二级展开。 - 改路径时同步顶栏、页脚、首页链接与旧路径引用。
文章风格
- 短句、直接、少形容词。 一段一个意思。
- 表格优先于长段落；步骤用有序列表。
- 先给角色/场景，再给操作。 需要时用「举例」小节，不要假设读者已懂内网拓扑。
- 口吻是官方文档，不是设计说明、不是 PR 描述、不是代码走读笔记。
自检清单（提交前）
- 用户能不能按文档独立完成，而不需要猜黑话？
- 侧栏有没有乱加 emoji？用语是否与上表一致？
- 涉及 Web UI 的关键步骤有没有配截图？