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 的关键步骤有没有配截图?