PostHog Context Layer Consolidation：用 `scripts/lint --report` 的确定性报告队列维护组织上下文 Wiki

PostHog Context Layer Consolidation用scripts/lint --report的确定性报告队列维护组织上下文 Wiki【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthogPostHog 的 Context layer 把每个组织的知识沉淀为一个 Git 仓库形式的 Markdown wiki由夜间 dreaming agent 持续维护。在维护闭环中context-layer-consolidation是一个有界清理技能它不生产新内容而是以scripts/lint --report产出的确定性发现stale 页面、过期优先级、幽灵链接等为工作队列对 wiki 做证据驱动的收敛。读完本文你能理解 consolidation 的完整工作流、报告队列中每一类发现的来源与阈值、结构错误与内容问题的职责边界以及为什么 agent 永远不能碰AGENTS.md、生成式索引和scripts/这些服务端拥有的文件。一、Consolidation 技能在 Context layer 中的定位Context layer 是 PostHog 托管的组织级 Markdown wiki每个组织一个 Git 仓库以git bundle序列化存储在对象存储中挂载进 agent 沙箱由夜间 Temporal 协调器context-layer-dream-coordinator03:00 UTC派发的 dreaming agent 维护见 products/context_layer/README.md。仓库中为这条维护链定义了三个 agent 技能职责严格分层技能职责性质context-layer-dreaming把近期组织活动Space 频道、已完成任务、合并 PR合成为带来源的事实页面生产context-layer-consolidation依据确定性 lint 报告队列收敛 wiki删除、合并、标记、拆分清理本文主角context-layer-health-check对 lint 报告之外的语义质量问题做复查矛盾陈述、近重复主题、缺 owner 页的概念语义评审dreaming 技能的第 6 步明确要求内容编辑完成后先跑scripts/lint然后运行scripts/lint --report生成 consolidation 队列见 context-layer-dreaming/SKILL.md 第 17 行。也就是说consolidation 是夜间 dream 运行中的一个受限阶段它在当前 dream 分支上处理队列——这正是 SKILL.md 第一句的出处。二、工作流先跑报告再按队列收敛SKILL.md 全文很短但每一步都对应源码中的具体机制Start withscripts/lint --report. Work the queue on the current dream branch.入口是报告模式scripts/lint --report除了输出结构性错误还会追加report_repo()生成的 advisory 发现下文第三节构成待办队列。只允许编辑带来源的内容页Only edit sourced Markdown content underorg/,areas/,decisions/, and existing Space pages.——这与服务端写入校验一致pages.py 的is_run_content_path只放行这四个目录下的.md页面且显式排除任何agents.md、claude.md、index.md。结构性失败不自己修Never edit repository instructions, generated indexes, orscripts/; report structural failures in the run summary for the server to repair. agent 只把结构问题记进运行摘要修复权留在服务端。这条边界有两层强制见第四节。收尾必须复验Keep this bounded and evidence-led. Runscripts/lintafter editing.——编辑后结构错误必须清零才能通过 land-time lint。三、报告队列report_repo的七类发现scripts/lint就是服务端 repo_lint.py 原样拷入 wiki 仓库的脚本scaffold.py 在 enablement 时直接Path(repo_lint.__file__).read_text()写入。--report分支由 main() 解析逐行打印report_repo()的发现。report_repo()repo_lint.py扫描所有org/、areas/、decisions/、projects/下的非 index 页面输出七类前缀化发现每类恰好对应 SKILL.md 的一条收敛规则发现前缀触发条件对应收敛动作stale:页面最后一次 git 变更超过 90 天通过git log -1 --format%ct计算见 _git_age()复查内容必要时删除或标记past_review:status: active且 frontmatter 的review_afterISO 日期已过期Remove expired priorities unless historically significant; mark thosestatus: historicalorphan:没有任何页面通过 wikilink 指向它inbound计数为 0合并或建立入链oversized:页面超过MAX_FILE_BYTES 16_00016 KBsplit oversized pagesmissing_sources:非decisions/页面没有sourcesfrontmatteradd sourcesdisagreement:正文匹配**Disagreement:**标记行DISAGREEMENT_REResolve disagreements only with evidence; leave the rest explicitghost_link:被引用的 wikilink 目标页不存在按目标聚合计数Repair or intentionally retain ghost links几个实现细节值得注意stale 依赖 git 历史_git_age() 对相对路径执行git log -1 --format%ct所以报告只在真实 checkoutdream 分支工作副本中有意义。wikilink 解析规则_wikilink_target() 剥离|别名、#anchor和.md后缀并拒绝绝对路径、..段和隐藏文件因此从旧主题留下 wikilink合并近重复页时必须指向真实页面否则本身成为新的ghost_link。全局边界整个 wiki 还受MAX_TOTAL_BYTES 50_000_00050 MB和MAX_FILE_COUNT 2_000约束repo_lint.py注释说明原因是读取时会从单个 checkout 预热每一页仓库必须远低于 worker 内存——这是拆超大页规则的系统级动机。四、结构错误 vs 内容发现两条互不越界的通道consolidation 技能反复强调report structural failures in the run summary for the server to repair这不是客套而是架构上的硬约束源码中有三重体现1.lint_repo与report_repo的失败语义不同。lint_repo()返回的是结构性错误main()只要拿到错误就return 1report_repo()的发现从不使 lint 失败。测试 test_report_findings_do_not_fail_lint 精确验证了这一点放入一个 16 KB 以上的页面后lint_repo仍返回[]而report_repo出现oversized:发现。这就是队列与门禁的分工——结构错误阻塞 landing报告发现只指导收敛。2.scripts/被逐字节钉死。_lint_scripts_directory() 用pin_scripts校验scripts/lint、scripts/publish与repo_lint.py中的PUBLISH_SCRIPT逐字一致must match the script PostHog ships; restore it from a fresh clone且scripts/下只允许这两个文件、禁止任何符号链接。test_repo_lint.py 的_scripts_tampered_lint、_scripts_symlink、_scripts_extra_file用例覆盖了对应的篡改场景。agent 想让违规编辑通过 linter的路径被从两端封死dreaming 技能明令 Do not change the wikis tooling to make a proposed edit pass服务端 land 时还会再跑一次同样的 lint。3. 服务端在 land 时复核 dream 分支的路径边界。store.py 会对 dream 分支做路径审计改动触及服务端拥有的路径时报错dreaming may edit context pages only; server-owned or structural paths changed: ...。服务端拥有的资产清单与 SKILL.md 的禁改清单完全对应AGENTS.md、CLAUDE.md必须是AGENTS.md的符号链接由 lint_repo 检查、每个index.md每次 landing 由 scaffold.generate_index 重新生成和scripts/。所以 consolidation 的操作空间被精确限定为内容页上的增、删、并、标记结构问题比如缺AGENTS.md、CLAUDE.md不是符号链接写进运行摘要等下一次服务端维护修复。五、七条收敛规则与 lint 约束的逐条对应SKILL.md 的核心是七条规则每条都能在 repo_lint.py 或脚手架里找到对应的机器可验证约束——这保证了证据驱动不只是措辞Remove unsupported synthesis.对应missing_sources:发现与 frontmatter 契约decisions/页面必须有非空sources第 148-149 行否则是 lint 硬错误其他目录的sources由报告建议。无来源的推断内容按 dreaming 技能的 admission test 本就不该入册。Remove expired priorities unless historically significant; mark thosestatus: historical.status取值由ALLOWED_STATUSES {active, superseded, historical}限定repo_lint.pypast_review:发现给出过期的review_after日期。Mark replaced decisionssupersededand link their replacement.这不是建议而是 lint 硬错误status: superseded的页面必须 wikilink 一个存在的替代页否则报superseded pages must wikilink an existing replacement第 154-155 行。脚手架里的 AGENTS.md 也复述了该规则Replace one by settingstatus: supersededand linking its replacement.Merge near-duplicates and leave a wikilink from the old subject.近重复的机器信号是 H1 标题归一化后重复第 156-162 行 对 H1 做casefold 非字母数字折叠后全 wiki 去重撞名即报duplicates the normalized title in ...。合并后旧路径要留一个 wikilink否则旧引用方会退化为ghost_link。Resolve disagreements only with evidence; leave the rest explicit.disagreement:发现会逐行打印**Disagreement:**标记DISAGREEMENT_RE把未解决冲突显式排队有证据才消解没有就原样保留——与 health-check 技能 的 Leave unresolved conflicts as**Disagreement:**markers 一致。Repair or intentionally retain ghost links, add sources, and split oversized pages.直接对应ghost_link:、missing_sources:、oversized:三类发现阈值 16 KB 来自 MAX_FILE_BYTES。Name every deletion in the commit message.与发布机制配合dream 分支最终以两父 merge commit 落库commit body 就是运行摘要见 dreams.py 的模块注释与 DREAM_SUBJECT_PREFIXgit log --merges即完整审计记录因此逐条列出删除项让每个D:状态的文件在git diff merge^1 merge中可追溯。六、编辑边界内的 Frontmatter 契约consolidation 会增删改 frontmatter边界由 lint_repo 的目录级检查框定所有页面summary单行用于生成index.mdstatus三态。review_after若存在必须是 ISO 日期。decisions/文件名必须匹配^\d{4}-\d{2}-\d{2}-[a-z0-9][a-z0-9-]*\.md$DECISION_FILE_RE且sources必填。projects/project-id/spaces/下的 Space 页team_id必须等于所在项目目录名channel_id必须存在、是 UUID 且必须是规范小写形式——_lint_channel_ids() 专门拦截大写/带花括号/urn:前缀等非规范拼写would land clean yet never match its own channel并保证同一channel_id不出现在多个页面。SKILL.md 的 existing Space pages 措辞即由此而来consolidation 只能改已有 Space 页不能新建或改名那是服务端 scaffold 的职责。编码与形态页面必须 UTF-8、非符号链接、.md根目录只允许AGENTS.md、CLAUDE.md、index.md与四个内容目录加scripts/。AGENTS.md 模板 中还给出三种页面模板area / decision / Space 页consolidation 拆分或新建页面时应沿用同样的 frontmatter 与段落结构area 页的 Current state / Direction / Linksdecision 页的 What / Why / Who。七、从编辑到落地lint、publish 与运行摘要consolidation 在 dream 分支完成编辑后的收尾链路scripts/lint结构错误必须清零。land 时服务端会执行同一份规则README 中 enforced by the linter (backend/repo_lint.py, also copied into the repo asscripts/lint)),agent 本地先跑只是比被拒的 commit 更便宜。提交并发布scripts/publish 把本地提交打包成git bundleorigin/main..$branchPOST 到 context layer commits 端点服务端 lint 后 rebase 到当前 headdream/YYYY-MM-DD分支则整体落为一个两父 merge commitdream: dategit revert -m 1可整夜回滚。发布需要POSTHOG_API_URL、POSTHOG_PERSONAL_API_KEY、POSTHOG_CONTEXT_LAYER_COMMITS_PATH三个环境变量沙箱内已注入见 facade/api.py 的SANDBOG_MOUNT_PATH/MOUNT_PATH_ENV_VAR/COMMITS_PATH_ENV_VAR定义。运行摘要即 merge bodydreaming 技能要求把摘要写到/tmp/dream-summary.md并scripts/publish /tmp/dream-summary.mddreams.py 从 merge commit 的 subject/body 解析出每次运行的summary与增删改页面计数Desktop 端通过GET context_layer/dreams/与GET context_layer/dreams/sha/回读。consolidation 报在运行摘要里的wiki-miss:行还会成为下一轮 health-check 的优先级信号health-check 技能 第 8 行。值得注意的是报告与 UI 是同一数据源pages.py 的 get_health_report() 在服务端 checkout 上执行同一个report_repo()把category: path: message拆成结构化的WikiHealthFindingcategory/path/message 三字段见 第 52-62 行缓存 24 小时后供 API 输出serializers.py。也就是说 consolidation 处理的队列与 Desktop 健康面板展示的是逐字段一致的数据。八、小结context-layer-consolidation的设计可以用三句话概括队列是确定性的所有工作项来自report_repo()的七类发现阈值90 天 stale、16 KB 页上限、50 MB 全库上限、2000 文件上限全部写在 repo_lint.py 常量里agent 没有自由裁量的要不要管。编辑是有界的只能动org/、areas/、decisions/与既有 Space 页的带来源内容AGENTS.md/CLAUDE.md/index.md/scripts/由服务端钉死并逐字节校验结构失败上报而非自修。收敛是留痕的superseded必须链向存在的替代页、合并必须留 wikilink、删除必须在 commit message 中逐一列名配合 dream merge commit 的不可变历史git log --merges、git revert -m 1整夜工作既可审计也可整体回滚。这套确定性队列 服务端结构所有权 证据驱动编辑的组合使 agent 对一个活体知识仓库的维护从开放式写作变成了可回归测试的工程流程——test_repo_lint.py 中的 16 个参数化违例用例正是这条流程可验证性的直接证明。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考