Skip to content

docs(ai-sre): fix drift and coverage gaps from doc-review audit (35 findings)#164

Merged
ysyneu merged 1 commit into
mainfrom
doc-review/2026-07-11-004443
Jul 11, 2026
Merged

docs(ai-sre): fix drift and coverage gaps from doc-review audit (35 findings)#164
ysyneu merged 1 commit into
mainfrom
doc-review/2026-07-11-004443

Conversation

@ysyneu

@ysyneu ysyneu commented Jul 11, 2026

Copy link
Copy Markdown
Contributor

Doc Review — 2026-07-11

Mode: audit (since N/A)
Scope: ai-sre
Findings: 36 total — 14 high, 15 medium, 7 low. Applied 35, skipped 1 (false positive, see below).

All content grounded in origin/main source reads (fc-safari backend + ai-sre-web frontend submodule); zh written first, en mirrored. Validated with mint broken-links (clean) and docs.json well-formedness.

Changes

Finding Type Doc Action
f001 missing_coverage sessions.mdx 新增「任务计划(Todo List)」小节:状态/优先级/当前步骤/进度环/暂停态
f002 missing_coverage sessions.mdx 新增「Agent 提问」小节:单选/多选/自定义文本/跳过/多题分页
f003 missing_coverage sessions.mdx 新增「需要授权时」小节:secret/OAuth 授权卡片、继续任务、链接过期
f004 feature_drift sessions.mdx 重写「Fork 会话」:Fork 弹窗中主动确认/更改团队与运行环境
f005 missing_coverage NEW artifacts.mdx 新建产物库页面(zh+en),注册 docs.json;automations/insight 补相关页面卡片
f006 missing_coverage overview.mdx 控制台导航表补「产物」行;sessions.mdx 补产物库链接
f007 stale_content knowledge.mdx 重写创建/编辑流程:无名称字段,仅范围选择(按真实弹窗/按钮文案)
f008 stale_content mcp.mdx 改写内置 Flashduty MCP Note:运行时注入,不再出现在列表;同页两处同前提表述一并修正
f009 missing_coverage mcp.mdx 基础字段表新增「执行环境」行(自动/绑定 BYOC Runner),与 OAuth 执行环境区分
f010 missing_coverage agents.mdx A2A 注册字段表新增「执行环境」行
f011 config_drift agents.mdx Card URL 校验描述纠偏:仅校验 URL 格式,网络边界由执行环境负责
f012 missing_coverage environments.mdx 新增「云端环境模板」章节:入口/字段/32KB env/64KB setup 脚本/网络访问仅全部允许/删除语义
f013 stale_content environments.mdx 合并重复的两个「权限配置」章节,保留双方独有内容
f014 stale_content automations.mdx 运行历史入口改为行点击→详情页右侧栏内联;清除历史图标/独立路由/死代码检视器描述
f015 config_drift sessions.mdx SKIPPED(证伪):引用的 maxLength=64 是搜索框;重命名后端硬限 60 rune,文档本就正确
f016 config_drift sessions.mdx 附件类型补文本/Markdown/CSV,新增单条消息总量 50MB 限制
f017 missing_coverage sessions.mdx 上下文引用补 @ 搜索插入故障引用入口
f018 missing_coverage sessions.mdx 新增「子任务(Subagent)」小节:芯片状态、分屏面板、展开/收起、单独停止
f019 stale_content sessions.mdx 初始化补第三阶段「运行 setup 脚本」与初始化失败错误态
f020 missing_coverage sessions.mdx 「编辑」语义改写为回滚:中断回合、禁附件、发送回滚按钮
f021 missing_coverage sessions.mdx 新增「选择运行环境」章节:自动/云端/BYOC 三段式选择器与状态
f022 missing_coverage skills.mdx 内置 Skill 补 gitlab(与 github 对称)
f023 missing_coverage skills.mdx 新增预装模板 Note:5 个 is_default=1 模板清单及来源说明
f024 missing_coverage skills.mdx 市场安装改为两步描述(+ → 归属弹窗 → 安装),清除「一键」措辞
f025 config_drift mcp.mdx 授权状态角标按模式区分:密钥=已保存/未填写,OAuth=已连接/未连接
f026 feature_drift apps.mdx 「关联新的组织」→ 实际按钮文案「更多仓库」(两处)
f027 missing_coverage automations.mdx 运行历史表补至 5 列 + 3 筛选(触发类型无 On-call incident 选项注记)
f028 missing_coverage automations.mdx 创建入口改为双按钮:「通过聊天创建」+「创建」
f029 config_drift automations.mdx 权限表拆分:个人规则仅创建者可管理(Owner/管理员无豁免,详情亦不可见)
f030 missing_coverage sessions.mdx 团队范围筛选补「全部团队/我的团队/指定团队」三态(默认我的团队)
f031 missing_coverage sessions.mdx 排队面板补可折叠/条数徽标/全部清空
f032 missing_coverage skills.mdx \/skill-name 转义写法
f033 missing_coverage skills.mdx 补斜杠补全「窄可见 + 宽解析」行为说明
f034 missing_coverage knowledge.mdx 补知识库加载失败横幅与重试机制
f035 missing_coverage apps.mdx 补 GitLab 不支持服务账号时选择器回退单选的行为
f036 missing_coverage environments.mdx 补 Docker 安装方式的卸载/彻底清除命令

Review checklist

  • Verify config field names and defaults match current code
  • Check that feature descriptions accurately reflect user-facing behavior
  • Ensure tone and style match the rest of the docs

Mapping warnings

None — all mapping paths validated against origin/main.

Skipped

  • f015: audit false positive. Sidebar.tsx:225 maxLength={64} is the session-list search box; the rename path is capped at 60 runes server-side (cmd/api/sessions Rename()), so the existing「最长 60 字」is correct.

Notes for reviewer

  • Findings source: .doc-review/findings-2026-07-11-001024.yaml (gitignored, local).
  • Excluded by design: K8s App/Agents (feature-flagged off on saas-prod), Routines(「敬请期待」占位页).

Apply 35 of 36 findings from audit findings-2026-07-11-001024:
new artifacts page (zh+en, registered in docs.json), cloud environment
templates section, session console interactions (todo list, agent
questions, authorization cards, fork dialog, rewind edit, environment
picker), MCP/A2A execution-environment binding fields, corrected stale
claims (builtin Flashduty MCP list row, automation run-history entry,
knowledge pack name field, A2A card URL validation scope, personal-rule
admin permissions), and merged the duplicated permission-config section
in environments.mdx. f015 skipped: doc already matches the backend
60-rune rename cap; the flagged 64 was the search box.
@ysyneu
ysyneu merged commit f812543 into main Jul 11, 2026
1 check passed
@ysyneu
ysyneu deleted the doc-review/2026-07-11-004443 branch July 11, 2026 08:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant