截至 2026 年 8 月 18 日，DeepSeek Harness 官方仓库中同时能看到根目录的 AGENTS.md、CLAUDE.md 与 .agents 目录这 3 类指令相关入口；仓库还处于开发者预览阶段，并明确提示可能出现兼容性破坏性变更。(github.com)
文件存在，但规则没有进入新会话 → 先固定启动目录和项目根，再验证候选文件、内容预算与覆盖层，最后用新会话或重启进程确认上下文已经刷新。
已经创建 AGENTS.md 但 Agent 仍忽略项目规范的开发者，应该优先看这篇。
维护多层目录或 monorepo 指令文件的技术负责人，可以用它区分路径问题、规则冲突和会话缓存。
迁移到远程 Mac 后行为变化的运维人员，则应重点检查工作区路径、DSH_HOME、权限和干净会话。
文件存在但规则未生效，通常卡在哪些环节？
最典型的失败案例是：你在仓库根目录新增了 AGENTS.md，编辑器或终端里也能正常打开它；但是启动一个已经存在的 DeepSeek Harness 会话后，Agent 依旧使用旧的代码风格、测试命令或目录约束。此时“文件存在”只能证明文件系统里有这份文件，不能证明它被发现、读取并放入本次请求的 workspace context。
常见限制至少有以下几类：
- 启动目录不一致。 终端命令可能从仓库父目录启动，Web UI 也可能保留上一次选择的工作区；你看到的文件和 Agent 实际扫描的目录不是同一个位置。
- 项目根识别错误。 monorepo、Git worktree、嵌套仓库或多个配置标记并存时，Agent 可能把子项目或父目录当成根目录。
- 候选文件冲突。
AGENTS.md、CLAUDE.md、全局指令和本地覆盖文件可能同时出现。官方仓库本身就同时维护这些入口，但这不能推导出所有版本都会采用相同的合并或优先级规则。(github.com) - 上下文容量不足。 指令文件太长时，可能影响总请求预算，或使真正的执行约束被背景材料稀释。不要把未经当前版本文档确认的固定字节数当作 DeepSeek Harness 的默认上限。
- 旧会话仍持有旧上下文。 许多 Agent 工具是在会话创建时组装系统提示词，而不是持续监听 Markdown 文件；因此修改文件后继续旧会话，不能作为文件监听功能存在的证据。
- 远程环境不等价。 迁移到远程 Mac 后，工作区挂载点、用户主目录、权限、软链接和环境变量都可能变化，导致本地能加载、远程却找不到。
如果你需要先确认远程 Mac 的交付条件，可先参考 远程 Mac 开发环境交付说明，但本文的重点不是迁移本身，而是判断规则到底在哪个时间点丢失。
第一步：会话创建前，先锁定工作区和项目根
在启动 dsh 或打开 Web UI 前，不要先改写规则。先把以下信息记录下来：
- 终端执行命令时的
pwd； - Web UI 中选择的工作区路径；
- 仓库实际根目录；
- 当前目录向上各级是否存在
AGENTS.md或CLAUDE.md； - 是否存在 Git worktree、子模块或第二个仓库；
DSH_HOME指向的位置，以及它是否与当前登录用户一致。
你可以先在一个最小测试仓库中复现，而不是直接拿业务 monorepo 排查。测试仓库只保留一个根目录标记、一个短小的 AGENTS.md 和一条不会修改文件的独特规则，例如要求 Agent 在回答中先输出固定的审计标签。这个标签只用于验证规则是否进入上下文，不要把真实密钥、内部路径或生产命令放进去。
项目指令文件应放在什么位置，才能被 DeepSeek Harness 识别？
不要凭其他 Agent 工具的习惯猜测唯一目录。对当前版本，应该以官方配置目录、架构文档和用户指南中实际启用的项目根标记与候选文件配置为准；如果版本允许显式指定候选文件，就把路径写入配置并记录启动时的工作区。官方仓库的根目录示例说明，项目说明文件可以与源码布局、工作区目录和子目录规则同时存在，但它不能替代你对运行时工作目录的核验。(github.com)
第二步：首次加载时，证明候选文件真的进入上下文
首次启动后，按下面顺序做一次无风险验证：
- [ ] 记录启动命令执行时的当前目录；
- [ ] 记录 Web UI 选中的工作区，不要只记录浏览器标签页；
- [ ] 列出全局指令、项目根指令和本地覆盖文件的实际路径；
- [ ] 检查文件名大小写、扩展名和软链接目标；
- [ ] 让 Agent 执行一条只读、可观察的独特规则；
- [ ] 保存 Agent 的原始响应，不要只凭主观感觉判断“它好像遵守了”；
- [ ] 在没有改业务代码的情况下，重新启动一次并重复同一测试。
验证规则最好满足三个条件：不会修改文件、不会触发外部服务、结果容易和未加载状态区分。例如，规则可以要求 Agent 在检查目录时先列出一个特定的检查顺序，或者在最终答案末尾加入一个仅用于测试的短标签。验证成功后，再删除这条测试规则，避免它长期污染项目指令。
自动读取并不等于必然生效。
不能把 DeepSeek Harness 对指令文件的支持理解成只要文件出现在磁盘上就必然生效。官方仓库确认存在 AGENTS.md、CLAUDE.md 等指令相关文件，但具体默认候选顺序、是否向父目录查找、是否监听修改以及 Web UI 如何反馈，都要按你正在运行的版本核对。(github.com)
如果没有可观察的加载证据，就把状态标记为“未证实”，不要把 Agent 偶尔答对一次当成规则已加载。模型可能根据代码、README 或用户问题猜到了同一个结论。
进入子目录后，规则集合可能突然变化
在 monorepo 中，仓库根会话和子目录会话不能默认视为同一上下文。你应当用同一个基准任务分别从根目录、服务目录和工具目录启动，并保存三份结果，比较以下内容：
- 根目录规则是否仍然出现；
- 子目录是否增加了更具体的规则；
- 同名文件是被合并、覆盖、折叠，还是只保留其中一份；
- 当前 Agent 访问的文件路径是否属于目标项目；
- 进入子目录后，工作区选择是否被 Web UI 重新解释。
重复内容可能被压缩或折叠，路径错位也可能让 Agent 读到另一个项目的规则。尤其是多个仓库嵌套、Git worktree 共用父目录、或远程 Mac 上通过软链接挂载代码时，pwd 看起来正确，并不等于根识别结果正确。
两个指令文件同时存在时，应通过对照实验确认关系。
不要自行假设 AGENTS.md 和 CLAUDE.md 一定是“前者优先”或“后者覆盖”。你需要查看当前版本的候选文件配置和架构说明，再用两个文件各写一条互不冲突、可观察的测试规则，分别启动干净会话。若两条规则都能验证，说明至少存在合并或串联；若只有一条生效，再继续核对候选顺序和覆盖层。
更稳妥的团队做法是：把稳定的项目约束放在一个主要来源中，另一个文件只保留适配当前 Agent 的短指针或必要差异，不要复制整份长文。官方仓库的 CLAUDE.md 与 AGENTS.md 维护关系也说明，实际项目可以通过链接或同步方式减少重复维护，但你仍应以当前版本的加载器行为为准。(github.com)
文件变长或格式异常时，如何确认忽略边界？
先检查文件本身，而不是继续增加提示词：
- 编码是否为标准 UTF-8；
- 是否含有不可见控制字符；
- Markdown 标题、代码围栏和列表是否意外未闭合；
- 文件权限是否允许运行 DeepSeek Harness 的用户读取；
- 路径是否指向已失效的软链接；
- 所有全局、项目和本地文件合计后，是否挤压了请求上下文预算。
不要虚构一个固定大小上限。若当前官方配置或源码没有明确给出默认值，就采用二分法：复制一份短规则文件，逐步增加背景材料，每次都用同一个独特标签验证，直到出现加载失败、响应变化或预算告警。这样得到的是当前版本和当前环境的边界，不是可以永久套用的产品常数。
建议把内容拆成两层：
- 稳定执行约束： 目录边界、禁止操作、测试命令、提交前检查；
- 任务背景材料： 架构说明、历史决策、接口解释、长篇示例。
前者应短、明确、可验收；后者放到 Agent 需要时再读取的文档中。官方仓库的指令文件本身也将目录结构、命令、测试和安全要求分成不同区块，说明“把所有知识塞进一份提示词”并不是稳定的维护方式。(github.com)
修改文件后，按三组会话对照确认上下文刷新
修改 AGENTS.md 后，至少做三组对照，不要只继续原会话：
- 旧会话继续执行。 观察它是否仍按旧规则回答，这只能说明历史上下文可能仍在。
- 新建会话。 使用完全相同的工作区和基准任务，验证新文件是否被读取。
- 重启运行进程。 如果新会话仍不一致，再重启
dsh或对应服务，排除进程级配置缓存。
每次测试都保存三类证据：修改前后的文件摘要、会话创建时间与工作目录、Agent 的可验证响应。若新会话生效而旧会话不生效，恢复标准已经满足，不需要继续追查文件监听。若重启进程后才生效，则应把“修改指令后必须重启”写进团队运维流程。
你还可以在规则中加入版本标记，例如 ruleset: 2026-08-a，但不要让 Agent 只复述标记就算成功；必须让它完成一条能区分新旧规则的只读动作。
迁移或远程重启后的端到端验收清单
远程运行后项目指令没有加载，通常不是提示词质量问题，而是环境交付不完整。使用同一测试仓库、同一基准任务和同一规则文件，逐项核对：
- [ ] 远程 Mac 上的工作区绝对路径与预期一致；
- [ ]
DSH_HOME已定位，并且运行用户确实读取到该位置； - [ ]
AGENTS.md、CLAUDE.md和配置文件已经随代码或部署资产交付； - [ ] 文件所有者、用户组和读取权限正确；
- [ ] Web UI 工作区与终端启动目录指向同一仓库；
- [ ] 远程会话不是从旧快照恢复；
- [ ] 使用干净会话重复独特规则测试；
- [ ] 本地与远程结果均已保存，能够逐项比较；
- [ ] 无法恢复时，明确回退到一个干净目录和全新会话。
如果远程环境的项目根、DSH_HOME 或权限无法确认，就不要继续重写 AGENTS.md。先参考 远程 Mac 交付验收方向，把工作区、环境变量和文件权限恢复到可核对状态；若你还需要比较多项目是否应隔离，也可以查看多项目工作区隔离相关说明。
当前方案和 Mac 方案，差别到底在哪里？
如果你现在是在本地临时目录、多人共用的远程 Linux 主机或反复重建的容器里运行，常见缺点是：工作区路径容易漂移、用户主目录和 DSH_HOME 不一致、文件权限需要人工补救，而且旧会话与新部署之间缺少稳定的验收基线。对于只做一次实验，这些问题可以接受；但当你需要重复测试规则加载、维护多个项目或让团队共享同一套排障流程时，环境差异会比提示词本身更快制造误判。
若你的目标是临时算力、短期验证或远程开发环境，租用一台由 KVMFLUX 交付的 Mac，通常更适合把工作区、权限和会话恢复流程固定下来。它并不适合所有人：长期稳定重负载、必须拥有物理接口或需要完全自主管理硬件时，自购 Mac 可能更合理；但在本篇这种“先复现、再验收、用完即释放”的场景里，稳定的远程 Mac 环境往往比反复改写规则文件更省排查成本。你可以先了解 KVMFLUX 的远程 Mac 使用场景，再决定是否需要租赁。