Agent 的构成与架构

「上线一个数字员工」落到机器上，究竟是什么东西？本页回答这个问题：一个 Agent 就是 AIDC Harness 里的一个 profile 目录，它的身份、记忆、会话、技能、定时任务、工作区与运行态全部住在这一个目录里；一个部门是一个 profiles 根目录；引擎是机器级的，与任何一个 Agent 的身份无关。理解了这三层，部署、备份、搬迁、隔离与退役都有了确定的答案。

// 一句话理解

AIDC 不发明自己的 Agent 结构。Harness 运行时本身就把「一个 Agent」定义为一个自包含的 profile 目录，AIDC 直接采用这个定义：一个目录 = 一个数字员工，一个根目录 = 一个部门域，一份引擎 = 一台机器。中枢只记它自己需要的东西（岗位、归属、策略、版本），不往 Agent 目录里塞私有格式。

什么是一个 Agent

在 Harness 里，一个 profile 就是一个独立的运行时主目录：它有自己的配置、凭证、人格文件、记忆、会话库、技能、定时任务和网关状态。两个 profile 之间不共享任何状态，因此同一台机器可以并排跑多个互不干扰的 Agent。AIDC 把「数字员工」一比一映射到 profile：财务部有七个数字员工，机器上就有七个 profile 目录，各自可以单独启动、停止、备份、搬走或删除。

这带来一个很实用的性质：Agent 的「存在」不依赖任何数据库记录或控制台页面。目录在，Agent 就在；把目录完整拷到另一台装了同版本引擎的机器上，它就在那台机器上继续工作，记忆与会话一并带走。控制台里看到的 Agent 列表是对这些目录的登记，而不是它们的本体。

三层：引擎、部门域、Agent

一台运行数字员工的机器上有三种东西，各自的生命周期与归属不同：

层	在机器上是什么	对应的组织单位	谁拥有它
引擎	一份按版本钉住的 Harness 安装，机器级共享	机器 / 基础设施	AIDC 发行，客户 IT 不改
部门域	一个 profiles 根目录：下面放各 Agent 的目录、域内共享看板与共享技能	部门	部门负责人；高敏部门可独占一块卷或一台机器
Agent	根目录下的一个 profile 目录	一个岗位上的一名数字员工	该岗位的负责人

三层之间的规则只有两条：引擎升级不动任何 Agent 目录；根目录本身不当 Agent 用。第二条是踩过坑才写下的：早期部署里部门的第一个数字员工直接住在根目录，结果引擎文件、共享物与它的私有状态混在一起，备份与搬迁都分不开。现在的标准是每一个数字员工，包括部门里的第一个，都是根目录下的一个子目录。

一个 Agent 目录里有什么

下面是一个数字员工目录的完整内容。这个清单不是 AIDC 设计的，而是 Harness 创建 profile 时固定生成的结构；AIDC 的贡献是把每一项对应到组织语言，并规定哪些是身份、哪些是状态、哪些是可丢弃的运行态。

config.yaml · .env · SOUL.md身份三件

配置（模型、工具集、终端与安全设置）、凭证（模型密钥、消息渠道令牌）、人格（它是谁、用什么口吻、避免什么）。复制一个 Agent 的「人」而不带它的「经历」时，拷的就是这三件。其中 .env 是唯一放密钥的地方，权限为仅属主可读，永远不进备份包与分享包。

AGENTS.md · MEMORY.md · USER.md岗位规则与记忆

三份 Markdown，职责截然不同：AGENTS.md 是岗位与项目规则，由人来写；MEMORY.md 是 Agent 自己学到的环境事实与工作惯例，由 Agent 通过记忆工具写；USER.md 是它对服务对象的了解，同样由 Agent 维护。人不要去改后两份，改了也不会变成人格，人格只认 SOUL.md。

state.db会话与消息真源

一个本地数据库，存全部会话、消息与全文索引。它是 Agent 目录里最重的一项：长期运行的数字员工可以累积到数十 GB，其中大半是全文索引而非对话本身。控制台里的会话侧栏读的是它的投影，本体始终在 Agent 目录里。

memories/ · sessions/ · plans/ · logs/长期记忆与过程记录

长期记忆文件、会话导出、任务计划与网关日志。记忆在每次会话开始时被冻结成快照注入，会话中新增的记忆写入磁盘立即生效，但要到下一次会话才出现在系统提示里。这是刻意的设计，为了保住模型的前缀缓存，因此「我刚告诉它就忘了」通常不是真忘了。

skills/ · cron/能力与定时任务

这个 Agent 可用的技能，以及它自己的定时任务。技能分两来源：引擎内置技能在引擎升级时自动同步到所有 Agent，用户改过的不覆盖；企业级技能由中枢按注册表下发，见下文「中枢管什么」。定时任务是 Agent 私有的，跟着目录走。

workspace/工作区（留空，真正的工作区在目录外）

运行时刻意把 profile 与工作区分开：profile 是「人」，工作区是「岗位上的桌面」，由配置项 terminal.cwd 单独指定，一个工作区可以被多名数字员工共用。AIDC 沿用这个模型，把工作区放在同一块部门卷上、profile 之外（见部门域）；profile 自带的这个 workspace/ 子目录只是兜底，留空不用。工作区不是权限边界，见下文「Agent、工作区与沙箱」。

home/子进程 HOME（容器形态用，宿主机上留空）

Agent 运行工具与脚本时的用户主目录，放语言运行时缓存、第三方工具配置这类工具状态，不是 Agent 的数据。在宿主机上运行时，运行时使用该数字员工操作系统用户的真实家目录，AIDC 把它放在部门卷的 homes/<岗位>/；profile 自带的这个 home/ 是给容器形态用的。

gateway.pid · gateway_state.json · processes.json · state/运行态（可丢弃）

网关进程号、通道连接状态、子进程表、生命周期哨兵。这些只描述「此刻正在跑的那个进程」，不是 Agent 的一部分：复制或搬迁时一律剥掉，否则新机器会误以为上一个进程仍在或非正常退出。

哪个文件管什么

大部分「它怎么不听话」的问题，都是改错了文件。这张表把最容易混淆的四份文件放在一起：

文件	装什么	谁来写	Agent 何时看到
SOUL.md	它是谁：人格、口吻、风格禁区	人（岗位负责人）	每次会话开始，系统提示第一槽
AGENTS.md	岗位与项目规则：流程、路径、约定	人	会话开始时从工作区加载，进入子目录时逐级发现
MEMORY.md	它学到的：环境事实、工具脾气、惯例	Agent 自己	会话开始时的冻结快照
USER.md	它对服务对象的了解	Agent 自己	会话开始时的冻结快照

想改它说话的方式，改 SOUL.md。
想让它记住一件事，直接告诉它，它会自己写进记忆；不要手改 MEMORY.md。
想立岗位规矩，写 AGENTS.md 放进工作区。
改了文件没反应，开一个新会话；上下文在会话开始时组装一次，运行中的会话不会重读。

Agent、工作区与沙箱

这三个词经常被混为一谈，但它们是三件事，而且 Harness 自己的文档说得很直白：profile 不是沙箱。

Agent（profile） 给运行时一个独立的状态目录。它隔离的是状态，不是文件系统访问权。
工作区 只是终端命令的起始位置。它不能阻止 Agent 读写目录之外的文件；问 Agent「你在哪个目录」也不是隔离测试。
沙箱才是限制文件系统访问的机制。人格文件可以引导模型，但不能强制边界。

所以 AIDC 的隔离不寄托在 profile 上，而是三道机器与制度层面的边界叠加：每个数字员工一个独立的操作系统用户，工具以该用户身份执行，别人的目录在权限上就不可读；部门域挂在独立的卷或机器上，高敏部门物理隔开；中枢下发的运行时策略在引擎层禁止一组高危命令，Agent 自己改不掉。这些都不是 Agent 目录里的东西，它们是「围着目录」的墙，详见 Agent Cell 与权限模型。

// 治理规则

不要用「给 Agent 写一段禁令」来代替隔离。一个数字员工能看到什么，必须由它的操作系统身份、所在的部门域与中枢策略共同决定；人格文件里的任何限制只当作礼貌提醒，不计入安全边界。

网关：每个 Agent 一个进程

每个数字员工用自己的网关进程接消息渠道，用自己 .env 里的渠道令牌登录，注册成机器上一个独立的系统服务。一个 Agent 的网关挂了只影响它自己；重启、升级、换模型都能逐个进行。两个 Agent 若误用了同一个渠道令牌，第二个会被引擎拒绝启动并指出冲突的对象，这条「令牌锁」防止两个数字员工顶着同一个企业微信或钉钉身份说话。

这是「原生」形态。AIDC 的分布式形态把同一个 Agent 目录当作快照存到对象存储，计算节点按回合唤醒、用完即弃，渠道由薄接收器持有。两种形态下 Agent 目录的内容完全一致，区别只在于目录住在常驻机器的磁盘上，还是住在对象存储里被按需投影。对照口径见 Company Harness。

中枢管什么，不管什么

AIDC Console 与它背后的中枢不持有 Agent 的本体，它登记与治理。下面这条线划得很清楚：

归中枢	归 Agent 目录
岗位与部门归属、负责人、操作系统用户号、引擎版本	人格、规则、记忆、会话
运行时策略：审批模式、禁令清单，按部门下发并热加载	模型、工具集等本地配置
企业技能注册表：发布一次，全舰队下次唤醒收敛；收回同理	Agent 自己安装或改过的技能
身份共享段：公司自述口径与行为红线，托管注入	岗位段人格：这个人是谁、管什么
Agent Key 网关：对外调用身份与配额	渠道令牌与模型密钥
健康与用量投影：只读的镜像	会话与消息的真源

原则是：中枢需要的字段记在中枢自己的数据库，不发明一个 agent.yaml 塞进目录；Agent 需要的东西放在 Harness 已定义的位置，不另起一套。这样引擎升级时 AIDC 不需要维护任何格式迁移，中枢更换时 Agent 也不受影响。

复制、搬迁与删除

Harness 区分两种「把 Agent 带走」，AIDC 各取所用：

语义	带什么	剔什么	AIDC 用在哪
分享式	人格、规则、技能、定时任务、记忆与会话导出	会话库、凭证、日志、缓存，并扫描脱敏	把一个岗位的「人设」复制到另一家公司或另一个部门；发布岗位模板
搬家式	整个 profile 目录，包括会话库与凭证	只剥运行态（进程号、连接状态、子进程表、生命周期哨兵）；工作区与 HOME 归部门卷，默认不带，按需复制	换机器、换部门域的卷

搬家的操作定式是：源机干净停止该 Agent 的服务，打包目录时保留访问控制属性与数字用户号，目标机以相同用户号建好操作系统用户，解包到部门域根目录，装上服务后启动。整个部门搬迁则不拷数据，直接把域卷卸下挂到新机器，再逐个补用户与服务。

删除一个 Agent 会同时停掉它的网关、移除系统服务与命令别名、删掉整个目录，操作前要求键入它的名字确认。AIDC 在此之上多一步：中枢里的岗位记录转为「退役」并归档它的会话投影，目录本身按数据保留期归档到对象存储后再销毁。

容量核算

一个数字员工占的空间看三处：它的 profile 目录、它的工作区、它的 HOME，三者都在同一块部门卷上，其中会话库、工作区是大户。部门卷按这三项之和的一点五倍规划，向上取整。全文索引是会话库膨胀的主因，定期瘦身索引比扩容更有效。