Product specification

Version: 2.5.104 (conversation orchestration target: help vs work stay separate; doing-work uses tools, not passphrase intent, 2026-09-05)

Consistency: Web and mobile both go through the Go backend REST; API and interaction detail take 后端与Web设计.md section 9 (confirmed decisions) in this directory as review truth (v7.0+ is aligned with the “in-house Runtime, do not call OpenClaw” narrative). From 2.0.0 this document is the primary product and technical spec for the outside.

Voice: For product capabilities, flows, and UI, always follow user language — natural wording people understand, who / situation / outcome as the subject. Implementation terms (API paths, database fields, runtime Workspace trees, and similar) appear only in §5–§7, implementation notes, or parentheses — do not replace what you say to users with implementation nouns. Naming: the onboarding conversation in Messages when no workspace is selected is called the help assistant in product and copy. Chat grain: a continuous Q&A chat is a conversation (implementation session / chat_sessions; do not say “session” to users); one user message plus the assistant finishing a reply (including tool round-trips in between) is a round (this round / last round / next round); one bubble is a message.

---

1. Project overview

1.1 Project name

Cadau

1.2 Project positioning

Cadau is an AI assistant product for enterprises and teams (multi-user, multi-workspace collaboration). Web and mobile both call business and conversation capabilities through the Cadau Go backend. The browser and mobile never talk directly to a third-party “agent gateway” (historically OpenClaw was planned; that is cancelled). Each user account is independent; users can create workspaces and invite or add other users into any workspace they created, collaborating inside that workspace. Shared resources, collaboration data, and quotas use the workspace as the main isolation boundary (personal resources still belong to the user dimension; see §1.5). Users register with phone, email, WeChat, or Alipay; sign-in is mainly phone or email + password or verification code (two main paths, password default; see §1.5.2).

The backend implements the originally intended experience on an in-house “agent runtime”: multi-conversation, user agents, skills and marketplace, memory and personalization, and similar. Inference goes through LLM APIs the server holds (OpenAI-compatible or other vendors). Cadau itself orchestrates Soul (persona and behavior core), Memory, and the execution pipeline, and no longer depends on an external OpenClaw service. Implementation uses the same “file-first Workspace” paradigm as OpenClaw (see §3.5): cognitive state lands as Markdown plus runtime tools to retrieve/write, implemented in Cadau code, not calling the OpenClaw gateway or CLI. The product needs self-evolution (see §3.6): inside the server loop, accumulate skill documents, long-term memory, user profiles and support cross-conversation retrieve and reuse, aligned with industry “persistent agents”, but implemented under enterprise SaaS audit and isolation.

1.3 Core value

• Under our control: agent persona, memory, tools, and conversation state are managed by Cadau’s own data model and runtime, so audit, compliance, and multi-workspace, multi-user scale are feasible.
• Keeps evolving: through §3.6 self-evolution and learning loop, the agent improves reusable skills and memory with use, instead of throwing a conversation away; evolution is configurable and auditable (differentiated from open-source single-machine assistants).
• Unified experience: one backend entry; brand and interaction stay consistent; extendable to Web, mobile, and SDK embed.
• Capability aggregation: LLM, retrieval, tool calls, and business APIs are orchestrated on the backend; keys are not exposed to clients.
• Workspace collaboration: several users in the same workspace share collaboration resources and context within authorization, supporting team scenes.
• Conversation as action: when the user says what they want done, the assistant does it; only when they ask “how / in what way” do you give a how-to. Missing parameters: ask; do not turn it into “please tap such-and-such page yourself”. See §4.1.5.

1.4 Target users

• Enterprise users: use an AI assistant to raise work efficiency.
• SaaS vendors: embed AI capability through the SDK.
• Teams and admins: need workspace-level collaboration, member invites, and permission split.

1.5 Accounts, workspaces, and collaboration

#### 1.5.1 User and workspace model

• User: each registered user is one independent account; accounts do not share personal data by default.
• Workspace (product concept): a user can create one or more workspaces; the creator can invite others into any workspace they created; collaboration and shared resources are bounded by the workspace (the same user may have different roles in different workspaces).
• Versus “runtime Workspace”: “workspace” in this section is the product collaboration unit; Workspace in §3.5 is the file tree under a single user-agent instance (SOUL.md and similar). Below, when needed, call it runtime Workspace, so it is not mixed with the product “workspace”.
• Business data (user profile, agents, conversation and message metadata, knowledge base, billing, and similar) must be stored and authorized with a user dimension; resources that belong to workspace share must also carry workspace_id (or equivalent) and check member identity; Runtime Workspace, memory, and self-evolution products (§3.5, §3.6) must be explicit about personal, workspace-shared, or agent-instance; default policy is defined in implementation and meets §3.6.2 isolation.
• No unauthorized cross-workspace read/write (forbidden to read another workspace’s data without authorization); ops and reports may aggregate by user and workspace.

#### 1.5.2 Register and sign-in (password and code, dual path)

• Two main paths: users may sign in with phone or email + password, or phone or email + one-time code to sign in/register; the two paths are equal in capability (both official sign-in); UI defaults to password (aligned with 界面与布局.md §2: default form is password; the code path is reached by Tab/switch on the same layer, not buried in a deep menu).
• Code path: uses POST /api/v1/auth/send-code, body distinguishing channel (e.g. sms / email) and scene (e.g. register, login, reset_password); after success, complete register / login with the code (field-level and error codes: 后端与Web设计.md section 9).
• Password path: set a password at register, check it at sign-in; one of the two completes sign-in (whether the same account may enable both is defined by implementation and security policy, and must be written in the API docs).
• New-user register: any one of four completes it: phone (characters in the picture + SMS code + password), email (characters in the picture + email code + password), WeChat scan, Alipay scan. Scan register does not need another phone or email code. This site cannot yet notify via WeChat or Alipay; after scan open, suggest filling a phone or email under Me for recovery and contact. If that phone or email is already registered, do not send a code and hint to sign in. While required items are incomplete, the register button stays untappable and says what is still missing.

#### 1.5.3 Workspaces and members (multi-person collaboration)

• Create a workspace: a registered user can create a workspace and become that workspace’s owner/admin (role names may be set in implementation); the system assigns a unique workspace_id. When they have not joined any workspace yet, the Messages empty state offers Create a workspace (default name “My workspace”) and Join a workspace (fill an ID to apply).
• Join a workspace: invite others into a workspace:

- Invite channel: phone or email (same as the account system); - Invitees accept with a code confirm or invite link + identity check, and become members of that workspace.

• Current workspace: after sign-in, if none is selected, automatically enter the account’s first valid workspace; if there are none, stay on the Messages empty state and hint to create or join.
• Start agent: when the user creates or newly enters a workspace and they do not yet have a work assistant, automatically create a work assistant named Start and open a conversation with it.
• Multi-person collaboration (product goal):

- Several members in the same workspace use shared resources within authorization, e.g. workspace knowledge base, team-visible agents/templates, conversation and task collaboration policy (sharing grain and RBAC land in phases; see §4.5). - Context switch: if the user belongs to several workspaces (created themselves or invited), the client and token must support switching current workspace; when accessing workspace-scoped resources, the backend resolves under workspace_id context, so data is not mixed.

#### 1.5.4 Time display and timezone preference

• Times the user sees: messages, notices, conversation “today/yesterday” grouping, tickets, train and approval records, embed/capability expiry, scheduled-task pickers and notes, release-note dates, register day, and every time shown to people, default Beijing time (UTC+8), Chinese dates, 24-hour clock, not following the browser system timezone.
• Changeable preference: under Me → Preferences → Time display (same area in mobile Me), the user may choose:

- Timezone (default Beijing); - Date format: Chinese year-month-day (e.g. 5 Aug 2026 in Chinese), year-month-day, year/month/day, month/day/year, day/month/year (default Chinese year-month-day); - Clock: 24-hour or 12-hour AM/PM (default 24-hour). After pick, all UI times convert by that timezone, date format, and clock. Each user configures independently.

• On-disk convention (implementation note): absolute instants on the server and in tables are still stored and transmitted in UTC; timezone, date format, and clock only affect how people see it. Scheduled-task “trigger at what o’clock” still computes in the task’s own timezone (default also Beijing) and may differ from the UI display timezone.
• “What time is it” in agent conversation: the runtime clock injected for the help assistant / work assistant prefers the current account’s display timezone (clock still 24-hour for parse); if the account has none, fall back to the deploy default (MINDLINK_RUNTIME_TIMEZONE, default Beijing). Scheduled-task trigger time still uses the task’s own timezone.
• API (implementation note): GET/PATCH /api/v1/auth/me reads/writes timezone (IANA, default Asia/Shanghai), date_format (ymd_cn / ymd / ymd_slash / mdy / dmy, default ymd_cn), time_format (h24 / h12, default h24).

---

2. Technical architecture

2.1 System architecture diagram

     LLM vendor APIs (keys and routing policy held on the server only)
                    ↑
          Cadau Go backend
   ┌──────────────────────────────────────┐
   │  REST API: auth, chat, skills, agents… │
   │  In-house agent runtime (Cadau Runtime) │
   │    · Soul config and parse               │
   │    · Memory write/retrieve/summarize     │
   │    · Conversation and tool-execution orchestration │
   │    · Self-evolution: skill deposit, memory promotion, profile, cross-conversation recall │
   └──────────────────────────────────────┘
                    ↑
        ┌───────────┴───────────┐
        │                       │
 Cadau Web              Cadau mobile
 (HTTP REST + JWT)      (HTTP REST + JWT)

2.2 Stack (clients and access layer)

2.3 Backend and runtime principles

---

3. In-house agent runtime (Cadau Runtime)

This section describes architecture capabilities that must be built in-house to realize the original product intent (names are spec language; implementation may map to modules/packages).

3.1 Soul (persona and behavior core)

Definition: structured config bound to a user agent or marketplace template, deciding who the agent “is, how it speaks, default goals, available tools and boundaries”, parsed at runtime into system prompt, policy, and tool list.

Requirements:

• Connect with user agents (user_agents) and marketplace templates (agent_templates) config models; support version and upgrade merge policy (see merge_mode and similar in the original spec).
• Support fields such as prompt, tool/skill binding, knowledge-source references; after train/publish, a Soul effective version update should fire (linked with train jobs).
• When running a conversation, Runtime assembles Soul with the current conversation and memory-retrieval results as model input (exact assembly is defined in implementation; must be testable and auditable).

3.2 Memory

Definition: storage and retrieval that keep multi-round conversation coherent and long-term personalization. At least these logical classes (physical storage may merge):

Requirements:

• Memory write, read, delete must authorize with user, agent, and workspace (if applicable) dimensions; in collaboration, “team-visible” memory needs an explicit policy, consistent with §1.5 and §3.6.2.
• External REST does not require exposing underlying memory-block IDs to the browser (unless the product clearly needs it); prefer using them indirectly through chat and “train/knowledge base” APIs.
• Async jobs for summaries and vector indexes, failure retry, and consistency policy should be defined in implementation and written into ops docs.

3.2.1 Knowledge base (global / workspace / user)

Voice: Product-side, knowledge-class materials agents retrieve and use as answer basis (how-tos are mostly Markdown; historical originals may also be stored; distinct from “in-conversation memory” and “dynamic deposit in long-term memory” in the §3.2 table) are collectively the knowledge base (UI subtitle may be “materials for answering in conversation”). Implementation may say knowledge storage root / mount; the old name “knowledge-document directory” is mapping only — tell users “knowledge base”.

To satisfy “in the same workspace, several user agents owned by different members can share one set of team knowledge” (similar to how the help assistant uses deploy-side HELP_DOCS_* global docs, but scoped from “all-tenant help” down to a workspace_id-bound collaboration boundary), the knowledge base is configured and retrieved in these three layers (merge policy and vector/full-text index are defined in implementation; must be auditable):

Split from §3.5 “runtime Workspace”: this section’s knowledge base is product knowledge that can be retrieved in bulk, layered global/workspace/user; §3.5 runtime directories are one agent’s Soul/Memory/daily-note execution state. Both may be spliced into the same conversation context at the orchestration layer, but isolation, quota, and ops are split.

Split from §3.2.2 standards library, §3.2.3 asset library, §3.2.4 check schemes: the knowledge base serves conversation Q&A and team wiki (not legal source of truth, not an apply-file cabinet); law and management-standard source of truth is the standards library; shared tables, forms/contracts and similar apply-files are the asset library; machine inspection packs after experts operationalize articles are check schemes (must cite standards, must not impersonate law) — four sit alongside; do not mix entries and storage.

Workspace and agent knowledge pages split into two blocks (same entry, not a separate plugin):

• How-to articles: keep writing Markdown (current wording, FAQ, processes). Figures still go in that article’s media/.
• Source archive: upload historical Word / Excel / PPT / PDF / images or scans; preview originals; mark current or archived. The assistant retrieves extracted text; under the answer, sources (how-to title or original filename) can be opened to preview the original. Originals do not go into the knowledge tree as .md bodies, and do not go into the asset library.

In conversation, related passages are taken for the question (not the whole tree dumped in). How-to articles use Generate index with AI to pick a topic then open the body; source archives match extracted text. A how-to of about 5,000 characters or less is one passage (good for one table, one data dictionary); longer ones merge by heading then split. Ordinary Q&A defaults to current only; when the user clearly asks “before / old notices / archive”, include archived items. The knowledge base does not generate vectors. When the user is looking up what was said in past conversations or which words were asked, do not retrieve the knowledge base (the assistant pages past conversations). The knowledge base offers retrieval test: type a sentence the assistant would hear, immediately see extracted how-tos (how-to articles via index, source archives via extracted text); if none relate, say nothing related was retrieved. Originals that failed parse clearly say they still have no passages. Only materials in the knowledge base are tested; past conversations are not paged.

• [x] Body figures and short video: Markdown documents can paste/upload png/jpg/gif/webp images, and a few to a dozen seconds of mp4/webm explainer clips (size cap about 8MB); they land in media/ beside the document. Width and left/right/center align can be adjusted in the editor; preview and agent Q&A can show images / play short video (conversation side loads with auth). (2026-07-25)
• [x] Source archive and passage retrieval: how-to articles and source archives are split; conversation injection carries sourced slices; effect (current/archived) participates in filtering. (2026-08-30)
• [x] Conversation sources and original preview: retrieved how-to articles / source archives are listed as “sources” under the reply; tap to preview. (2026-08-30)
• [x] Retrieval test: the knowledge base can trial-retrieve, showing only truly extracted related how-tos and the method used (how-to index / source archive); if none relate, say nothing related was retrieved. Does not page past conversations. (2026-09-02)
• [x] Looking up past conversations does not pull the knowledge base: asking what was discussed recently or which words were asked leaves knowledge retrieval empty, so near-miss policy notes are not used as sources. (2026-08-30)
• [x] Users call it “knowledge base”: UI and help no longer say “knowledge-document directory” to users; implementation paths and mount names stay. (2026-09-02)

3.2.2 Standards library (laws and management standards)

Voice: Laws, industry standards, management policies, and management theory maintained in a workspace are collectively the standards library (UI subtitle may be “laws and management standards”). It is the shared source of truth for plugins such as HR and compliance and for agent Q&A — not a private folder of one plugin, and not an alias of the §3.2.1 workspace knowledge base.

Mechanism detail: docs/core-mechanisms/规范库.md.

Requirements (product decision, 2026-07-25):

• [ ] Workspace isolation: standards are stored and authorized by current workspace; forbidden to read across workspaces.
• [x] Entry metadata: title and body (or attachment), type (law / industry standard / internal policy / management theory, and similar), domain tags, document number and issuing body (when applicable), effective/repeal dates, source (manual or official site), status (draft / pending review / published / repealed), version. (Phase 1 shipped)
• [x] Body format: Markdown; edit/preview switch; figures and short explainer videos in the entry media/, body uses relative paths; width and align adjustable (paste or pick upload; video ≤ about 15 seconds, ≤ about 8MB). (2026-07-25)
• [x] Multi-dimension index trees (browse, not a knowledge folder): the workspace presets classification dimensions such as region / industry / type; each dimension is a manageable tree. The same standard may hang on several nodes. UI “switch index → left tree → middle list → right body”; the tree is a browse index, not a knowledge physical directory. Detail 规范库.md §4.7 (shipped 2026-07-25).
• [x] Admin entry: collaboration-page intro + “Manage standards library” → /workspace/standards full-screen admin; keep draft/review/publish/repeal.
• [x] Import/export: admins can import / export (zip; includes body, figures, and classification attachments); import supports incremental (same skip, draft update, published not overwritten); must review and publish again.
• [x] Agents write drafts: when a workspace is selected, agents may use system tools to write/update standards-library article drafts (user must confirm; forbidden to auto-publish); split from knowledge-document and check-scheme tools. (2026-08-07)
• [ ] Source allowlist: auto-crawl only official domains/entries registered on the workspace; addresses outside the allowlist must not write auto-update results.
• [ ] Crawl split from publish: after a work assistant or scheduled task crawls an official site, results enter draft/pending review; only after publish do they affect ordinary-member Q&A and plugin generate. Laws and mandatory standards default to human review; an enable date may be set.
• [ ] Agent Q&A: default retrieve only published, enabled, not repealed standards; answers should cite basis (document number/version/source) where possible. Business facts (roster, inspection conclusions, and similar) still go through each plugin’s controlled operations; must not impersonate live business data with the standards library; must not inject check-scheme bodies as law.
• [ ] Plugin share: the platform provides read-only capability so connected platform plugins read published standards by domain tag or index node; plugins may prefill surveys, show citations, and similar, but machine packs that generate check items are §3.2.4 check schemes; must preview and human-confirm then write the plugin business store, recording standard ID + version (and scheme ID + version).
• [ ] Change broadcast: after a new version is published, push an impact list to plugins subscribed to that domain; forbidden to silently overwrite already-stored business rules and data; support rolling back a published version.
• [ ] Plugin-to-plugin: cross-plugin business calls (e.g. compliance looking up HR) go through Cadau sign-on-behalf and audit; full legal text is read from the standards library by each party, not passed between plugins as source of truth.
• [ ] Versus factory templates: plugins may ship default templates; published workspace standards may override or trim defaults.
• [ ] Versus asset library: a standard may be cited as “based on” from an asset-library entry; blank business tables / filing templates themselves live in §3.2.3 asset library; do not use the standards library as a file cabinet.
• [x] Versus check schemes (2026-08-07): expert practice machine packs do not enter the standards library impersonating articles; they go in §3.2.4 check schemes, with required citation of this library. Mechanism detail docs/core-mechanisms/检查方案.md, 合规实践检查表转机读包.md.

3.2.3 Asset library (templates and tables)

Voice: Team-shared tables, form templates, contract samples, blank checklists, and presentation/document/spreadsheet styles you made that can be downloaded and applied, collectively the asset library (UI subtitle may be “templates and tables”). It serves members applying, agents filling forms into attachments, platform plugins picking templates at onboarding/inspection. It is not §3.2.1 knowledge documents (wiki), not §3.2.2 standards library (article source of truth), not §3.2.4 check schemes (machine packs), and not chat attachments or a private references/ inside a skill pack.

Mechanism detail: docs/core-mechanisms/资料库.md.

Requirements (product decision, 2026-07-25):

• [ ] Workspace isolation: assets are stored and authorized by current workspace; forbidden to read across workspaces.
• [x] Entry metadata: title, short note, file (and version), type (presentation style / document style / spreadsheet style / table template / form / contract sample / blank checklist, and similar), domain tags, status (draft / published / repealed), version; optional based on standards (standards-library ID + version).
• [x] Permissions: members can browse and download published entries and see their own drafts. Office styles (presentation/document/spreadsheet styles) are published and repealed by the uploader; contract samples, checklists, and similar are still published by the workspace creator/admin. Import/export still admins only. Applying an office style copies as a new attachment; it does not overwrite the asset-library original.
• [x] Agent use: conversation injects matching asset metadata; filling a form into a new attachment depends on office/script capabilities; forbidden to overwrite the asset-library source of truth.
• [x] Plugin share: GET /platform-plugins/assets… read-only published assets and file streams; when picking, record asset ID + version.
• [x] Split from neighboring objects: chat attachments, skill references/, app templates, agent marketplace templates do not act as the asset library; do not store Excel/Word primarily in the knowledge base (historical originals go to source archive; apply-files go to the asset library).
• [ ] Index browse (later): may browse by an index tree of domain/use (same family as the standards library: the tree is a filter view, not a knowledge physical directory); phase 1 may use a flat tag list.
• [ ] Hard quota gate and auto-fill toolchain (later).
• [ ] Quota: file occupancy counts toward workspace storage quota (consistent with §4.5).
• [x] Entry: in workspace collaboration, shown alongside “knowledge documents”, “standards library”, “check schemes”; collaboration intro + “Manage asset library” → /workspace/assets full-screen admin (back + title + workspace name; left list / right metadata, preview, and download; filter by status, type, keyword). Does not copy the standards-library index tree and Markdown body. (2026-07-25; preview 2026-08-25)
• [x] In-page preview: right side splits “Detail / Preview”; default detail only; tap Preview to use the same preview as conversation “work results” for tables, documents, presentations, PDF, images, Markdown, and similar; may go full screen; apply still downloads as a new file and does not change the original.
• [x] Import/export: admins can import / export (zip; includes notes and files); import supports incremental (same skip, draft update, published not overwritten); must publish again.
• [ ] Practice-checklist raw material (2026-08-06): when type includes checklist, it may be the input of the compliance “practice checklist → machine pack” skill; conversion results go to §3.2.4 check-scheme drafts, not storing the machine-pack source of truth in the asset library. See docs/core-mechanisms/合规实践检查表转机读包.md, 检查方案.md.

3.2.4 Check schemes (practice machine packs)

Voice: Machine inspection packs (and similar standard packs) maintained in a workspace after operationalizing standards-library articles are collectively check schemes (subtitle may be “practice machine packs”). They answer “how do experts suggest you inspect, so you meet the standard” — not the legal text itself, and not Excel/Word originals in the asset library.

Mechanism detail: docs/core-mechanisms/检查方案.md; conversion flow: 合规实践检查表转机读包.md.

Requirements (product decision, 2026-08-07, option B):

• [x] Workspace isolation: schemes are stored and authorized by current workspace; forbidden to read across workspaces.
• [x] Entry metadata: title, description, machine body (Markdown), domain tags, status (draft / pending review / published / repealed), version; required based on standards (standards-library ID + published version, may be several); optional source asset-library entry.
• [x] Publish gate: cannot publish with no cited standards; after admin publish, plugins may pick; forbidden to auto-publish.
• [x] Admin entry: collaboration page alongside standards/assets; “Manage check schemes” → full-screen admin (/workspace/check-schemes).
• [x] Agents write drafts: system tools write/update check-scheme drafts (user must confirm); forbidden to impersonate a check scheme with a standards-library entry or knowledge document.
• [x] Plugin pick: compliance questionnaires prefer a published check scheme (UI shows cited standard titles/versions); generating check items needs preview and human confirm; transition may fall back to a standards-library entry.
• [ ] Q&A boundary: default do not inject check-scheme bodies as “what the law says”; articles still come only from published standards-library content. (System prompt already guides; retrieval injection boundary still to strengthen)
• [x] Stock migrate: machine packs wrongly published as standards-library “practice entries” can migrate via “Manage check schemes → Migrate from standards library”, fill citations; after migrate, repeal/delete the original practice-pack entry.
• [x] Import/export: admins can import / export (zip; includes body and cited standard titles/document numbers); import supports incremental (same skip, draft update, published not overwritten); cited standards re-attach in this workspace by title/document number where possible; must review and publish again.
• [ ] HR and similar extension (later): machine standard packs such as competency may join this model; phase 1 is compliance-first.

3.3 Execution and orchestration

Definition: control flow that turns one user request into a model call, optional multi-step tool calls, then a summarized reply.

Requirements:

• Support a unified or layered model of Skills and tool calls; consistent with POST /api/v1/skills/execute and in-chat trigger policy (see historical decisions or this document section 3.4 feature list).
• Support idempotency: client request_id and backend dedupe (see section 4).
• Streaming output (SSE/WebSocket) may be a phase-2 enhancement; phase 1 may stay full JSON responses like history, but architecture should reserve a streaming extension point.

3.4 Mapping to original functional requirements

Business goals in the original spec — Web chat, attachments, multi-conversation, skill list, agent marketplace, paid and train — stay; the change is only the substrate from “talk to OpenClaw” to “in-house Runtime + LLM API”. If the admin console once included “OpenClaw run management”, it should become ops objects such as model routing, runtime health, memory indexes, and train-job queues (detail may be a separate admin-spec revision; see section 10).

3.5 File-first Workspace (implementation paradigm, isomorphic with OpenClaw)

This section agrees how Cadau implements §3.1–§3.3: one runtime Workspace per user agent + fixed-semantics Markdown files + runtime tools, isomorphic with OpenClaw Memory / Workspace / SOUL public description (easier for the team to understand and compare), but all inside Cadau process and storage, not depending on OpenClaw binaries, gateway WebSocket, or CLI. Note: Workspace here is a runtime directory tree, not to be mixed with the product workspace in §1.5 (collaboration unit); use context when names collide.

#### 3.5.1 Runtime Workspace boundary

#### 3.5.2 Standard files (names and duties)

The following paths and filenames relative to the Workspace root are a product/engineering convention (implementation may also generate indexes or derived files, but must not break these semantics).

Note: these files are all Markdown text; what the model “can remember” is what is actually written to the Workspace and retrieved via Memory tools, consistent with OpenClaw’s “no hidden state, disk is truth”.

#### 3.5.3 Runtime tools (capabilities the model may call)

Runtime should expose to the LLM a minimum set isomorphic with OpenClaw memory tools (names may match, for prompt migration):

Optional enhancement (phase 2): wiki-style knowledge layer (aligned with OpenClaw memory-wiki plugin idea), wiki_search / wiki_get, and similar, for structured knowledge and provenance.

Memos (separate from memory): records the user stores on purpose (text / files / images), retrieved by tag (unique / repeatable) and saved date, like a small asset library for that agent. Not auto-injected every round. In default conversation mode, memo_* is called only when the user clearly wants to save or look up a memo (including looking up employees, leave, expenses by tag); the user may switch the conversation to memo mode, after which unless they say otherwise, reads and writes target memos (they can still clearly say “write into memory” to reroute); after switching to memos a memo pane appears beside the conversation and refreshes as soon as the assistant changes a memo; after close, the leftover “Memos” button can also be dragged elsewhere. After picking memos in the pane, they can change or delete them directly in conversation. Files and images need a content note from the model when saving or overwriting. Mechanism: docs/core-mechanisms/智能体备忘.md.

#### 3.5.4 Orchestration and concurrency (execution pipeline)

#### 3.5.5 Prompt assembly order (implementation constraint)

When assembling system-side context for the LLM, suggested order: base system prompt → SOUL.md → AGENTS.md → USER.md (if any) → retrieved Memory slices → current conversation messages; token allocation and truncation are detailed in implementation docs; must be unit-testable (the same Workspace file version should correspond to a deterministic input summary).

#### 3.5.6 Boundary with REST / clients

• Clients only call REST listed in §5; they do not touch Workspace paths or raw files such as SOUL.md.
• Config the user changes through agent config, train, knowledge base and similar APIs should be synced to the matching Workspace files or a new version generated, so files one Runtime run reads match the DB effective version.

3.6 Self-evolution and learning loop (Evolution Loop)

This section defines Cadau self-evolution: without depending on an external Hermes / OpenClaw process, the agent accumulates and reuses knowledge and capability through server closed-loop jobs and Workspace on disk. Important: industry “self-improve / learning loop” (e.g. Hermes Agent) usually is not “only auto-generate skills”, but a combination of skill deposit, memory solidify, user modeling, history retrieve; Cadau aligns with the full vision, and adds mandatory governance for multi-user, multi-workspace.

#### 3.6.1 Sub-paths (spec semantics)

The following sub-paths together make self-evolution; implementation may phase, but data model and Workspace convention must reserve extension so later work is not thrown away.

Note: OpenClaw Dreaming mainly maps to memory promotion in the table above (background tidy, promote long-term memory); it is not the whole skill-deposit line. Industry Hermes-style “self-evolution” is closer to the multi-path combination above — this section uses that full definition, so “self-evolution” is not narrowed to one mechanism.

#### 3.6.2 Enterprise governance (required vs open-source assistants)

#### 3.6.3 Tools and extensions (suggested)

• MCP compatible or adapted: the tool surface should support a standard protocol (e.g. MCP) for external capabilities, so skills from “evolution” combine with new tools with less change to core orchestration (consistent with §3.3 tool model).
• Execution isolation: if a skill involves code/Shell execution, it must go through sandbox, approval, or enterprise policy (implementation elsewhere), so “the more it evolves, the more dangerous” is avoided.

#### 3.6.4 Boundary with REST

• Self-evolution trigger, config, review happen through backend APIs and the admin console; clients still only use REST in §5, and do not write Workspace files directly.
• What users see: more accurate memory, smoother skills, a closer profile, written to Workspace and indexes by closed-loop jobs behind the scenes.

---

4. Functional requirements

4.1 Web client

#### 4.1.1 Connection and auth

• [ ] Complete register/sign-in through the Go backend (password or code dual path, UI password default, see §1.5.2), get JWT; JWT/conversation must express current user, and when collaboration resources are involved express current workspace (if the user has joined or created one); production does not connect any LLM or internal runtime-admin endpoint from the browser.
• [ ] Call /api/v1 with an HTTP client; on 401 try refresh and replay by existing policy (detail: 后端与Web设计.md section 9).
• [ ] Connection/health: mainly backend reachability, signed-in state, and in-request status.

#### 4.1.2 Messages

• [ ] Send text messages (POST /api/v1/chat and similar, response body aligned with backend ChatResponse).
• [ ] Chat attachments: upload associated with chat messages.
• [ ] Receive AI replies (server return is truth).
• [x] Message timestamps and role distinction (user/assistant): when the gap is about 5 minutes or more, show time centered (today time only, across days include month-day), similar to WeChat. (2026-07-31)
• [ ] Multi-conversation, list pagination and message pagination, skill-list pagination.
• [ ] Send retry carries client request_id for idempotency.
• [x] Generate a PDF (work assistant): after office-document tools are on, tell the assistant or tap the entry above the composer to generate a laid-out .pdf in one shot (shares platform styles with Word). No need to write a script, and no need to produce Word then Save As. (2026-09-01)
• [x] Reading mode (Web): turn the conversation into continuous prose, collapse sidebar and composer, for reading on e-ink and similar; type size adjustable; jump by question; export the current conversation as an ebook (EPUB) or PDF. (2026-07-29)
• [x] Conversation-pack import/export: pack one conversation, take it away, import on another server into another agent, open as a new conversation and continue. Takes user and assistant bodies and attachments; not tool process. Can also tell the assistant “export this conversation / import a conversation” to do it. (2026-08-27)
• [x] Reply annotation improve (Web): tap “Mark up” on an assistant reply, write notes under each original paragraph (may add overall requirements), then “Improve from notes” for the agent to rewrite. (2026-07-29)
• [x] Conversation work-results area (Web): besides expand/collapse/not-embed in the bubble, file preview can move to the right of the conversation; default follows “Me → Preferences”. The preview-position icon appears in the composer only when this round already has files; one tap switches between bubble and right (when switching back to bubble, last in-bubble preference is kept). When there are results, the feature menu and conversation history collapse automatically; several results can page previous/next, or jump by filename, default latest. Conversation history can be pinned; when pinned it no longer auto opens/closes with work results. (2026-08-26)
• [x] Conversation topic and review (work assistant): each conversation has a current topic (the user’s main goal, Markdown one paragraph or several, shown formatted, editable). The topic is background; this turn follows the latest user message and is not a command. New questions are answered directly; rewriting the stored topic still needs the user to say so. Saying add a bit, replace a whole paragraph, or tighten is enough; the assistant understands then writes; no need to memorize a passphrase; not written to long-term memory. By default do not nag for review. After “Prompt for review” is on in agent settings, prompt the current way: after at least two rounds, when the assistant judges it is done, a Review button appears; idle more than 2 hours and less than 2 days, the assistant invites in the same conversation. When off, they can still say “review this”. Review is drafted by the assistant, confirmed by the user, five columns: what got done, key decisions, user requirements and corrections, unfinished items, reusable practices. Help assistant / embed / scheduled conversations do not do this. Mechanism: docs/core-mechanisms/对话主题与复盘.md. (2026-09-04: topic is not a command)
• [x] Scripts fill capability (work assistant): when built-in tools cannot do it but Python can, the assistant says which library to install, what it can do, and which current problem it solves. After the admin allows, install the library on the spot, write code, finish, and deposit a workspace skill for later reuse; ordinary members apply to an admin. Excel / Word / PPT still use office-document tools. Mechanism: docs/core-mechanisms/工作区能力包.md §2.4. (2026-08-26)
• [x] Look up past conversations (work assistant): tell the current assistant “look up English words I asked in the last three days’ conversations” and similar; the assistant retrieves conversation originals by date (need not write memory or daily notes first). Only your chat with this assistant; not colleagues or visitors. The help assistant does not do this. Mechanism: docs/core-mechanisms/查看过去对话.md. (2026-08-30)

#### 4.1.3 Skill features

• [ ] Shortcut-command trigger (phase 1 may go through chat content or the skills API).
• [ ] Skill list display (GET /api/v1/skills).
• [ ] Skill invoke (POST /api/v1/skills/execute or merged with chat consistently).

#### 4.1.4 Interface features

• [x] Messages-sidebar agent groups (Web): agents you created appear in the “I created” subgroup, same width as “System”; beside the title you can tap Adjust groups. The dialog exits only by top-right close or “Cancel” (tapping the mask does not close). You can have the assistant pile by name, then change group names; drag an agent onto an existing group (or select first then tap a group). The help assistant, app assistants, and Service notices stay in the “System” subgroup. User groups are stored in the current workspace. (2026-08-28)
• [ ] Sidebar navigation, sign-in/register/forgot-password flow (codes go through send-code; support create/switch workspace and invite members entries; see §4.5).
• [ ] AI conversation page.
• [ ] Skill management page.
• [ ] Settings page (API base URL may show only in development).
• [x] Responsive design, mobile adaptation; help-class read-only pages, theme, and i18n: 界面与布局.md.

#### 4.1.5 Action assistant and help assistant (conversation actions)

• [x] In each console module, the user can open the action assistant anytime and ask in natural language “what should I do next”; the assistant may combine the current product UI to guide. The action assistant and the help assistant are the same identity.
• [x] When opening an app (HR, warehouse, and similar), the bottom-right is the workspace app assistant. If no more than 20 minutes since last open or speak, continue the previous conversation; more than 20 minutes then open starts a new conversation. Left open without speaking more than 20 minutes, collapsing then opening also starts a new conversation. They can still pick an earlier one from “Past conversations”. The help assistant is not affected by this interval.
• [x] The assistant panel bottom offers a few quick prompts (one tap carries a preset question and jumps to the related capability page). These entries adjust order and copy with which block you are looking at, whether a workspace is selected, and what you just said in the assistant, preferring what you are more likely to ask next; the user is not required to understand the ranking rules.
• [x] Conversation actions (ChatOps, product core): when the user says what they want done, do it; only when they ask how / in what way give explanation and entries. For example “help me create a workspace”, “switch to…”, “create an agent”, “generate a skill”, “create an app”, “invite a member”, “approve a join request”, “add a data connection”, “list departments”, “inbound” — the system writes by the current user’s permission, not only a how-to then asking them to paste on a page. Invite, remove, delete, open a page, and similar change/delete/navigation must be confirmed by the model reading the full sentence, so “remove wording / summarize the topic” is not treated as removing a member. Work still to continue this round (change topic, remember) is understood by the current assistant then tools are called, not passphrase intercept; “how / in what way” and short answers already in confirm still accept fixed wording. Create, rename, switch, delete a workspace need not select a workspace first (create asks for a name first; if none, use “My workspace”); when a workspace is selected, creating an agent writes to the current workspace; when creating a workspace or agent, if the sentence already ends with a name (e.g. “create agent Test”, “create a agent, CRM”, “create a new workspace, DEMO”), use it directly and do not ask; when creating an agent, if a fixed phrase did not extract a name but the original sentence still has content that might be a name, reread the whole sentence to fill, and only then ask; if doing-work was mis-treated as create and similar platform operations and the user corrects next round, record the misread so later similar wording confirms first; if an agent was just created by mistake, remove it first (not when they only wanted a rename); when creating an agent, if they also said temperature (0–2), write it on that agent too. Plugin business goes through the matching app assistant operation list (the help assistant, given the same request, must also do it). Other writes with no workspace selected first ask the user to pick a workspace. The help assistant has no personal memory and memos; scheduled tasks must name the work assistant to bind. Mechanism: docs/core-mechanisms/帮助智能体对话操作.md (what chat can already do); how each round selects materials and calls tools: docs/core-mechanisms/智能体对话编排.md (target; help assistant and work assistants stay separate identities).
• [x] App assistant recognizes the form being filled (platform-plugin convention): when the user opens a fill overlay in any app, the assistant can tell which form is being filled; natural-language extras write back into that draft and show immediately, without tapping save or create first. Every app with a fillable UI must connect; mechanism: sdk/platform-plugin/README.md §6.1. HR already connects this way. (2026-08-28)
• [ ] Implementation and extension (scoring signals, candidate pool, reachability with no workspace): docs/core-mechanisms/工作区帮助快捷一句.md.

4.2 SDK embed pack

#### 4.2.1 Web Component

• [x] Custom element <mindlink-widget>
• [x] Shadow DOM isolation
• [x] Theme config (light/dark/auto)
• [x] Position config (bottom-right/bottom-left/middle-right/center/inline)

#### 4.2.2 Config parameters

#### 4.2.3 My-agent JS embed (V1)

• [ ] Embed target: an external system embeds “My agents” with a snippet of JS (<script src="...">), completing AI conversation and controlled actions on the host page.
• [ ] Bound object: the embed instance must explicitly bind user_agent_id; if omitted, init throws and does not enter a conversational state.
• [ ] Init: support window.MindLinkWidget.init(...) (or equivalent API) and <mindlink-widget ...> with the same parameter semantics.
• [ ] Minimum parameters: user-agent-id and auth.token required; also give base-url or api-base-url. app-id, auth.expires_at, workspace-id, theme, position, locale, entry, host_actor (required on path B) are optional.
• [ ] Auth constraints: the embed must not hold the main system’s long-lived keys; only use a short-lived token issued by the server (including expiry, accessible scope, optional workspace_id constraint).
• [ ] Conversation: embed conversations run through the backend chat contract; several visitors may talk at once (inside one conversation, still one round at a time). Concurrent generating replies are capped (configurable per agent, default 20; when over, the widget says “conversation count is at the limit, try later”). New conversations must check user_agent_id availability and authorization.
• [ ] Controlled actions: when the agent triggers an action in embed, it must go through allowlisted actions (e.g. open_url, open_module, emit_event); arbitrary script execution is forbidden.
• [ ] Event callbacks: at least onReady, onMessage, onAction, onError, onClose; the host may listen and decide whether to allow high-risk actions.
• [ ] Safety baseline: Shadow DOM isolation, origin check (Origin Allowlist), suggested CSP, and action audit logs (including request_id, user_agent_id) on by default.
• [ ] Degrade and fault: on token expiry, network error, or insufficient permission, show an error people understand, and offer re-authorize or retry.

First delivery mapping (2026-08): Script / Web Component embed, embed-token register and revoke, POST /api/v1/chat/stream, in-answer mindlink://action/ and entry.auto_execute_navigation (on by default), updateAuth / updateHostActor, Shadow DOM, inline + container, human support / tickets, answer “next step” chips, when copying the script optional entry shape (corner button / first greeting / open already expanded) and panel name, already shipped; see sdk/host-embed/SDK契约.md §6.3 and sdk/host-embed/网站集成说明.md. Origin allowlist, action cards, dedicated embed_token_expired error code still planned.

#### 4.2.4 Two business-integration shapes (host enhance / platform plugin)

Cadau and external business products have two typical joins (they may coexist); both must check current user at the integration layer, and when a workspace is involved also workspace_id and workspace-member identity; forbidden to access plugin-side data across workspaces or without authorization.

• Host enhance (existing business system): the user still uses the existing business system as the main UI and permission boundary; Cadau, through §4.2.3 “My agents” embed and similar, adds AI conversation and controlled actions to that host (contract: sdk/host-embed/SDK契约.md). When business data is not stored in Cadau, conversation must not invent field-level conclusions the host did not authorize.
• Platform plugin modules (new business products): independently developed and deployed business apps (own Web and tenant model; server APIs may deploy same-origin with the front end (e.g. Next.js) or split into several services) join Cadau; users enter the module from the workbench or sidebar menu, forming a unified “Cadau gained a professional capability” experience; Cadau only owns the navigation shell, account/workspace context, and available agents (joined to plugin business through short-lived tokens and an explicit workspace ↔ plugin enterprise/tenant map). Compliance, approval, reports, and similar inside the plugin are still implemented and audited by the plugin service. Laws and management standards shared by several plugins are §3.2.2 standards library (not in one plugin’s private knowledge tree); cross-plugin business calls must be platform-signed and audited. Fill overlays opened in an app must be recognized and filled back by the app assistant (§4.1.5, sdk/platform-plugin §6.1), independent of whether it is HR.

Samples (in the repo): plugins/hr/ — official platform plugin (HR); plugins/mfg-hr/ — official manufacturing HR platform plugin (factory org, attendance/payroll, plant ops; spec truth plugins/mfg-hr/docs/产品规格.md); plugins/compliance/ — official compliance platform plugin (questionnaire → check items → bind a workflow → inspect the HR department; IWAY is only a replaceable sample standard, laws/management policies also work); plugins/warehouse/ — warehouse; plugins/email/ — email (IMAP receive / SMTP send; spec truth plugins/email/docs/产品规格.md); plugins/camera/ — camera (face-recognition network cameras: access, clock-in/out attendance; two security uses, each page visible, restart need not re-pick; after a violation may send SMS (a digit string as a reminder) and/or email (including a snapshot), one channel only is OK; continuous recording and playback by time, occupancy and segment length limitable; spec truth plugins/camera/docs/产品规格.md); examples/hr-multi-tenant/ — multi-role run of the HR sample + host-embed comparison; examples/henry-iway-compliance/ — “Henry Iway” branded platform-plugin sample (integration language: its docs/PRODUCT.md); for runnable official compliance, prefer plugins/compliance/.

Compliance · practice checklist → machine pack (product decision, 2026-08-06; store target corrected to check schemes on 2026-08-07):

• [x] The compliance plugin ships with the skill “Practice checklist → compliance machine pack” (may distribute with the repo skill catalog); when opening Compliance, prompt to install into the workspace Skills center (agents in the workspace can recall by default); forbidden to silently rewrite each agent’s “available skills” narrowing config. (2026-08-06 phase 1)
• [x] Through an agent, the user turns an expert practice table in the asset library (or an attachment) into a machine pack and writes a check-scheme draft (must confirm; citing standards suggested); after publish, pick the check scheme in a questionnaire to generate check items; stock practice packs wrongly in the standards library can migrate from the standards library. (Compliance-side independent “validate/preview” can still be strengthened; see §3.2.4)
• [x] Practice machine packs supplement “how to inspect”; they do not replace standard articles in the standards library; generating check items still needs preview and human confirm. Detail docs/core-mechanisms/检查方案.md, 合规实践检查表转机读包.md; sample plugins/compliance/samples/iway6-internal-audit-g1.pack.md.

4.3 Agent marketplace and user agents

Business goals and confirmed policy (hybrid template instances, commercial model, take rate, quantity limits, soft delete, train scope, review, conversation binding, and similar) keep the product conclusions from the 1.x spec; implementation is supported by Runtime Soul/Memory/orchestration, no longer through OpenClaw.

4.4 Self-evolution (product capability)

• [ ] Skill deposit: support generating or updating skill documents from tasks/conversations (versioned, retrievable), consistent with skill list/execute API policy; support boundary with marketplace templates and train jobs (see §3.6.1).
• [ ] Memory promotion: support flush + Dreaming-like background jobs (can turn off, configure frequency and threshold), promoted content writes MEMORY.md and similar; summary surface may connect DREAMS.md (§3.5).
• [x] Cross-conversation recall: a work assistant can retrieve this account and this assistant’s conversation originals by date and keywords (conversation_search / conversation_get); do not auto-inject full text. Long-term memory still uses memory_search. Mechanism: docs/core-mechanisms/查看过去对话.md. (2026-08-30)
• [ ] User profile: USER.md (or equivalent) updates gradually under policy; sensitive items need explicit authorization or a review policy.
• [ ] Governance and ops: evolution job queue, failure alerts, quota and audit query; admin console can view/intervene (consistent with §3.6.2).

4.5 Workspace collaboration (product capability)

• [ ] Workspace context: when accessing workspace-scoped resources, the request runs under the current workspace; support switching among several workspaces, then refresh lists and data.
• [ ] Create a workspace: a registered user can create a workspace and get that workspace’s owner/admin permission.
• [ ] Invite members: send an invite to a phone or email; the invitee signs in/verifies then joins the matching workspace.
• [x] Members and roles: workspace identity distinguishes owner/admin/member; inside a workspace you can customize business duties (process claim and capability-pack grants); finer identities and owner-transfer policy can keep evolving. (2026-08-03)
• [ ] Collaboration resources: in the same workspace, knowledge base, agents, conversation policy and similar open team-visible / self only share modes by product phase; consistent with Runtime memory isolation (§3.2).
• [x] Standards library: the same workspace maintains laws and management standards (§3.2.2); API + conversation injection + multi-dimension index trees and full-screen admin (2026-07-25); pending source-allowlist crawl, plugin-subscribe impact lists.
• [x] Asset library: the same workspace maintains templates and tables (§3.2.3); full-screen admin + API + plugin read-only + conversation metadata injection (2026-07-25); pending index-tree browse, hard quota gate, auto-fill toolchain; mechanism: docs/core-mechanisms/资料库.md.
• [ ] Quota: per workspace member count, agent count, storage, and similar configurable caps, stackable with user-level quota (may merge with “user grade” and similar policy).

4.6 Unified chat and contacts (product capability, confirmed 2026-05-23)

Mechanism detail: docs/core-mechanisms/统一对话与联络.md.

Relation to §4.1: the top-bar Messages entry becomes the unified conversation entry (same list and bubble UI as people, leased agents, and group chats); inference with agents still goes through Cadau Runtime, but no longer treats “only chat_sessions owned by the current user” as the long-term unique conversation product model.

#### 4.6.1 Unified conversation

• [ ] One interface: in one conversation list the user sees colleagues, agents, and workspace groups; after opening any conversation, send and receive text and attachments on the same timeline (attachment policy aligned with §5.2 upload).
• [ ] Agents are also conversation members: agents you created can be talked to directly; leased agents appear in the conversation like people; replies are generated by server Runtime and written into the same conversation.
• [ ] Display: messages show under the agent identity (e.g. “Someone’s · tax assistant”); both the lessor and the lessee can set a remark name for the same agent; the UI prefers the remark name.
• [ ] Help assistant: onboarding conversation when no workspace is selected may still use the help path; whether it finally joins the unified entry or keeps a shortcut is decided at implementation; users must not confuse colleague messages with help.

#### 4.6.2 Agent leasing (public marketplace)

• [ ] Public marketplace: an owner can list a trained agent for others to browse, apply, or pay to lease (payment, orders, and billing may land in phases).
• [ ] Lease contract: AI call consumption is billed to the lessor, lessee, or workspace as the lease contract / plan says (not one global rule).
• [ ] Join a group: in a workspace group they have permission for, the lessee can add a currently valid leased agent for @ in the group or replies triggered by rules.

#### 4.6.3 Person-to-person chat and friends

• [ ] Does not depend on a workspace: add friend and person-to-person chat are bounded by account; the user need not have joined any workspace; only workspace group chat and same-workspace colleague trusted 1:1 depend on workspace membership.
• [ ] Same-workspace colleagues: treated as a trust relationship; 1:1 need not add friend first, and the “only one message before they reply” rule does not apply.
• [ ] Neither colleague nor friend: WeChat-like stranger rules — only 1 message before they reply; after they reply, enter short-term chat (duration or message cap by implementation); long-term contact requires being friends.
• [ ] Friends: after mutual friends, free 1:1 chat; support friend request, reject, block (copy must avoid implementation terms).

#### 4.6.4 Workspace group chat

• [ ] Default all-member group: each workspace automatically has an all-member group; members sync as people join/leave the workspace.
• [ ] Self-created subgroups: members or admins can create subgroups (project groups and similar); rules are managed by group roles (phase 1 may be only “pull people in”).
• [ ] Group members: people + agents that meet lease/authorization; group messages are only accessible to members related to that workspace (and lawfully leased agents).

#### 4.6.5 Implementation notes (not user copy)

• Suggested API prefix for the new conversation domain: /api/v1/im/ (distinct from the existing /api/v1/chat human–assistant path; they may coexist during migration); tables are separate from chat_sessions / chat_messages; see the mechanism doc §3–§7.
• Safety: authenticate conversation-member identity for everyone; lease billing and audit bind lease_id; stranger/friend rules only constrain person↔person.

---

4.9 Agent team meetings (product capability)

Mechanism detail: docs/core-mechanisms/智能体团队会议.md.

• [x] Entry: top-bar feature menu Agent team (same level as workflows and workspace collaboration); a workspace must be selected. The old “Workspace collaboration → Agent team” redirects here. (2026-08-23)
• [x] Team roster: a workspace can form an agent team; first pick a common lineup template (product launch / content publish / customer go-live / compliance review) or create roles from scratch, then assign a work assistant to each role (each role can decide). (2026-08-23)
• [x] Publish a task and meet: after a member publishes a task, the system opens a project group, pulls in the role agents, and discusses by agenda; a decision by the matching role takes effect immediately — no waiting for someone to click during the meeting. (2026-08-23)
• [x] Stop: a member can stop the whole meeting; emergency brake, not stepwise approval. (2026-08-23)
• [x] Continue: if a role did not decide or the meeting stopped, tap “Continue meeting”, or say “continue meeting” / “keep refining” in the group, or @ the role with another requirement. (2026-08-23)
• [x] Coding crew: the development role can dispatch code changes to Cursor / Codex / OpenCode / a custom crew; the crew is not a meeting member. (2026-08-23)

4.7 Service notices (product capability, confirmed 2026-05-25)

Mechanism detail: docs/core-mechanisms/服务通知.md.

• [ ] Fixed entry: in the Messages module, pin Service notices; alongside the help assistant, business agents, and colleague conversations; the name is fixed and does not change with workspace.
• [ ] Read-only timeline: show system-sent explanations and tappable actions (e.g. “Handle this”, “Open workspace collaboration”); cannot reply; do not generate notice body with a live large model.
• [ ] Usable without a workspace: account-level events (e.g. receiving a workspace invite) still deliver; the top-bar Messages unread badge merges AI-conversation unread and service-notice unread.
• [ ] Phase-1 events: workspace invite, join request submit/approve/reject/withdraw, invite accepted, and similar (detail mechanism doc §5.1); handling UI stays in workspace collaboration; notices are for reach.
• [ ] Read: entering Service notices updates the read watermark; the top-bar badge decreases accordingly.
• [x] WeCom reach (workspace capability pack WeCom): after an admin connects a self-built app and binds members, service notices and scheduled tasks that checked “also push to WeCom” can go to the person; unbound members stay in-product only. DingTalk / Feishu / email channels are not done. Mechanism: docs/core-mechanisms/工作区能力包.md §2.7. (2026-08-29)

4.8 Human support and tickets (product capability)

Mechanism detail: live — docs/core-mechanisms/人工客服.md; async tickets — docs/core-mechanisms/工单.md.

• [ ] Per-agent config: each agent (including the workspace help assistant) can turn on human support separately and assign this-workspace support seats; they may instead authorize a support team without ticking local people. Do not default workspace admins as support. When on, both live and ticket entries are available.
• [ ] Live human support: shortcut Human support → queue (position / wait estimate) → talk online; after it ends, the record stays in the current conversation; the customer can end it; after end, five-star rating (agent performance). When nobody is on duty (neither local seats nor authorized team on duty), only Submit a ticket remains.
• [ ] Tickets (async): shortcut Submit a ticket; no real-time requirement; pending / in progress / closed; can leave messages; after close, can rate. While in the live queue they can switch to a ticket.
• [ ] Support desk: top bar Support (local seat or support-team member) or the feature menu. One top row: title on the left; range combobox / on-duty status / refresh on the right. Left segments: Live support (waiting / mine / in progress / closed), Tickets, Duty hours. Team members can switch This-workspace support / Team desk (the latter only customers already authorized and in service scope). Taking a ticket on the team desk does not switch the top-bar current workspace.
• [ ] Support team: this-side workspace admin creates the team, names members, and picks workspaces to serve; it takes effect after the customer workspace admin authorizes. All three gates (members + service scope + authorization) must be in place before they can see and take that customer’s tickets. Authorization grants support rights only; they do not become members of the customer workspace.
• [ ] Config entry: self-built agent → Manage → Human support; help assistant → Workspace collaboration → Support queue (left: Requests / This-workspace support / Our teams / Authorize outside teams).

#### 4.8.1 Implementation notes (not user copy)

• Config: user_agent_cs_config, user_agent_cs_staff.
• Support teams: cs_groups, cs_group_members, cs_group_workspace_grants, cs_group_workspace_scope.
• Live conversations: cs_tickets, cs_ticket_messages (do not call these tickets on the user side).
• Async tickets: support_cases, support_case_messages.
• API: see the two mechanism docs; Web: /customer-service; help-assistant placeholder ID: __builtin_assistant__.

---

5. Data format and API conventions

5.1 Web client and backend (REST)

• Auth header: Authorization: Bearer <token> (access / refresh policy: 后端与Web设计.md §3.2 and section 9 decisions, or backend implementation); for workspace-scoped resources, the token or companion header/field must express current workspace_id (or equivalent); the server authenticates by user + workspace membership; purely personal resources authenticate by user.
• Rate limit: HTTP 429, JSON includes error, retry_after, may include request_id, and may set Retry-After header.
• Other 4xx / 5xx: error JSON fields error (required), code, request_id, details (optional).
• Success 2xx: JSON top-level request_id; request-body idempotency request_id is not the same as the response trace ID.
• Pagination: limit + cursor; default limit = 20; next_cursor and similar: 后端与Web设计.md section 9.
• OpenAPI: phase 1 does not require a generable Swagger; the contract is this document and backend code.

5.2 Main endpoints (summary, aligned with 1.x)

Agent-marketplace endpoints (agent-templates, user-agents, train, and similar) field-level convention: §7.4; when implementing, update implementation notes with Soul/Memory as the landing criterion.

5.3 Front-end message types (UI layer)

interface Message {
  id: string
  role: 'user' | 'assistant' | 'system'
  content: string
  timestamp: Date
  attachments?: Attachment[]
  metadata?: Record<string, unknown>
}

type AppConnectionStatus = 'disconnected' | 'connecting' | 'ready' | 'error'

5.4 Internal runtime message flow (implementation reference, not a client protocol)

The client uses REST only. The following is server-internal sketch (not a public WebSocket contract):

1. Auth and conversation resolve → resolve user, current workspace (if the business binds one), the runtime Workspace for user_agent_id, load SOUL.md / AGENTS.md / USER.md and Memory retrieve (§3.5)
2. Assemble the LLM request → optional tool loop (memory_search / memory_get and similar)
3. Persist messages and memory-file updates → return ChatResponse

---

6. Project structure (sketch)

mindlink/
├── sdk/                    # SDK embed pack
├── client/                 # Web / Mobile clients
├── backend/                # Go: REST API + Cadau Runtime + LLM gateway
└── docs/
    ├── 产品规格.md                      # This requirements spec (primary)
    ├── 后端与Web设计.md    # Web through backend: confirmed decisions (section 9)
    ├── 界面与布局.md              # Web UI conventions
    ├── 文档索引.md                  # Doc navigation (Chinese filenames)
    ├── 管理员端规格.md              # Admin-console functional spec and ops appendix
    ├── 实施计划.md / 实施验收.md
    └── 手机验证码发送集成说明.md    # SMS-channel integration (with DESIGN decision 35)

---

7. API reference (Web client)

7.1 Backend access conventions

• HTTP client: interceptors, timeout, 401→refresh→replay (see 后端与Web设计.md section 9).
• Endpoints: section 5.2; fields and error codes follow the Go implementation in the repo.

7.2 Front-end service modules (sketch)

function getAccessToken(): string | null

async function login(body: Record<string, unknown>): Promise<AuthResult>
async function register(body: Record<string, unknown>): Promise<AuthResult>
async function sendCode(body: { channel: 'sms' | 'email'; scene: string; [k: string]: unknown }): Promise<void>
async function resetPassword(body: Record<string, unknown>): Promise<void>
async function sendChat(input: { message: string; session_id?: string; request_id?: string; user_agent_id?: string }): Promise<ChatResponse>

7.3 Agent marketplace APIs (summary)

The following paths are exposed by the Go backend; conversation and train orchestration are done by Cadau Runtime, not through external OpenClaw.

7.4 Agent marketplace API contract (field-level, V1)

The following is the phase-1 suggested contract; actual implementation may adjust field names without breaking semantics.

#### 7.4.1 Unified pagination

• Request params: limit (default 20), cursor (optional)
• Response fields: items, next_cursor (null when no more), optional has_more
• Sort suggestion: marketplace list by published_at desc; my agents by updated_at desc

#### 7.4.2 Templates (agent_templates)

1) POST /api/v1/agent-templates (create draft)

Request sketch:

{
  "name": "财务助手 Pro",
  "summary": "处理报销与对账",
  "category": "finance",
  "pricing_mode": "subscription",
  "price_amount": 39.9,
  "price_currency": "CNY",
  "base_config": {
    "system_prompt": "你是财务助手",
    "tools": [],
    "knowledge_sources": []
  }
}

2) PATCH /api/v1/agent-templates/:id (update draft / rejected draft)

• Allowed updates: name, summary, category, pricing_*, base_config
• When status=published, do not overwrite directly; go through a “new version draft” flow (suggested)

3) POST /api/v1/agent-templates/:id/submit-review (submit for review)

Optional request field:

{
  "changelog": "新增考勤异常处理工具"
}

4) Review state machine (templates)

• draft -> pending_review -> approved -> published
• pending_review -> rejected
• rejected -> draft (can submit again after edits)
• published -> unpublished (unlist; does not affect already-created user instances)

#### 7.4.3 User agents (user_agents)

1) POST /api/v1/agent-templates/:id/create-user-agent (create instance from template)

Request sketch:

{
  "name": "我的财务助手",
  "request_id": "optional-idempotency-key"
}

Response sketch:

{
  "user_agent": {
    "id": "ua_xxx",
    "name": "我的财务助手",
    "source_template_id": "tpl_xxx",
    "source_template_version": 3
  },
  "entitlement": {
    "pricing_mode": "subscription",
    "valid_until": "2026-05-01T00:00:00Z"
  },
  "request_id": "srv_xxx"
}

2) POST /api/v1/user-agents (create a blank agent)

{
  "name": "空白助手",
  "system_prompt": "",
  "tools": [],
  "knowledge_sources": []
}

3) PATCH /api/v1/user-agents/:id (update instance config)

• Updatable: name, system_prompt, tools, knowledge_sources
• On update, suggested to increment config_version for audit and rollback

4) DELETE /api/v1/user-agents/:id (soft delete)

• Suggested behavior: is_deleted=true, keep a restore window (e.g. 7/30 days)
• After soft delete, default cannot create new conversations; historical conversations remain read-only

5) POST /api/v1/user-agents/:id/upgrade (manual upgrade)

{
  "target_template_version": 5,
  "merge_mode": "prompt_only"
}

Suggested merge_mode:

• prompt_only: upgrade system prompt only
• safe_merge: upgrade template defaults, keep user custom overrides
• force_replace: fully replace from the template (high risk; suggested second confirm)

#### 7.4.4 Train jobs

1) POST /api/v1/user-agents/:id/train

{
  "mode": "full_rebuild",
  "knowledge_file_ids": ["file_1", "file_2"],
  "tool_bindings": [
    { "tool_id": "attendance.query", "config": {} }
  ]
}

2) Suggested job status: queued -> running -> succeeded/failed/cancelled

3) Suggested extra query APIs:

• GET /api/v1/user-agents/:id/train-jobs
• GET /api/v1/train-jobs/:job_id

#### 7.4.5 Conversation and agent binding

POST /api/v1/chat request sketch (adds user_agent_id):

{
  "message": "本月薪资核算流程",
  "session_id": "optional",
  "user_agent_id": "ua_xxx",
  "request_id": "optional-idempotency-key"
}

Rules:

• New conversation: user_agent_id required
• Existing conversation: default keep the conversation-bound user_agent_id
• Switch agent: do not switch inside the original conversation; need a “new branch conversation” bound to the new user_agent_id

#### 7.4.6 Billing and entitlement (V1)

• pricing_mode: free | buyout | subscription
• Platform take rate fixed: 20%
• Suggested order fields:

- order_id, buyer_user_id, template_id, pricing_mode - gross_amount, platform_fee_amount, creator_income_amount - status: pending/paid/refunded/closed

• Entitlement check:

- free: always valid - buyout: permanently valid after payment succeeds - subscription: valid only when valid_until > now

#### 7.4.7 Suggested business error codes (extra)

• agent_quota_exceeded: exceeds how many the user grade may create
• template_not_published: unpublished template cannot create an instance
• template_review_pending: template is in review; publish-related operations forbidden
• entitlement_required: missing purchase/subscription entitlement
• subscription_expired: subscription expired
• agent_deleted: agent already deleted
• session_agent_mismatch: conversation does not match user_agent_id
• upgrade_conflict: upgrade version conflict
• train_job_running: a train job is already running

7.5 My-agent embed contract (field-level, V1)

This contract is for “an external system embeds my agent with a snippet of JS”; embed-side capability boundary and auth policy align with §4.2.3.

Implementation alignment: integration and TypeScript types take sdk/host-embed/SDK契约.md (currently V1.5.10) and the deliverable integration guide sdk/host-embed/网站集成说明.md. This section keeps a product field-level summary; when it conflicts with “current implementation” notes, those two win.

#### 7.5.1 Init params (widget init)

The host page can pass the following equivalent params through window.MindLinkWidget.init(options) or <mindlink-widget ...>:

Init sketch:

{
  "base_url": "https://mindlink.example.com",
  "user_agent_id": "ua_123",
  "auth": { "token": "eyJ..." },
  "theme": "auto",
  "position": "bottom-right"
}

Path B also passes host_actor, and may explicitly give app_id, api_base_url, workspace_id, auth.expires_at.

#### 7.5.2 Embed auth and token claims

• The embed side does not hold Cadau main-system long-lived keys; in production the host backend signs a short-lived (or registered long-lived) token then gives it to the browser (see sdk/host-embed/网站集成说明.md §4.3).
• Current JWT Claims (authx.Claims): sub, wid (workspace), emb=1, jti, exp; the JWT does not contain app_id / user_agent_id; those two are constrained by init and embed_access_tokens registration.
• Protected APIs: Authorization: Bearer; when emb=1, middleware checks the registration is not revoked and not expired; revoke returns embed_token_revoked.
• Expiry/signature errors: currently folded into unauthorized (copy “token invalid or expired”); dedicated embed_token_expired is still planned; the front end should rely on updateAuth or the host re-signing.

#### 7.5.3 Conversation request and response (embed mode)

The embed widget currently uses POST /api/v1/chat/stream (SSE), not sync POST /api/v1/chat. Request-body example:

{
  "message": "请帮我总结今天未完成的任务",
  "session_id": "optional",
  "user_agent_id": "ua_123",
  "request_id": "req_embed_001",
  "client_context": {
    "channel": "embed_widget",
    "app_id": "crm-prod",
    "page_url": "https://crm.example.com/home",
    "host_actor": { "external_user_id": "…", "actor_kind": "employee" }
  },
  "host_actor": { "external_user_id": "…", "actor_kind": "employee" }
}

Constraints:

• A new conversation must explicitly provide user_agent_id.
• An existing conversation defaults to the existing agent binding; switching agents in the same conversation without a prompt is not allowed.
• client_context is already sent by the client and parsed by the server: when channel=embed_widget (or JWT emb=1), conversation source is recorded as embed; app_id is written to the conversation’s embed_app_id; host_actor (or the same-named top-level field) is used for conversation isolation and data-connection policy.
• In embed mode all high-risk operations can only be issued through the action allowlist (see §7.5.5); mindlink://action/ links in the answer, when clicked or triggered by auto_execute_navigation, fire an action event executed by the host allowlist.

#### 7.5.4 Event callback contract (host may listen)

Suggested standard events:

Event sketch:

{
  "type": "action",
  "request_id": "srv_abc",
  "action": {
    "type": "open_url",
    "payload": { "url": "https://crm.example.com/order/123" }
  }
}

#### 7.5.5 Controlled-action allowlist (V1)

Phase 1 allows:

• open_url: open a business page (needs domain allowlist check).
• open_module: tell the host to switch to a registered module.
• emit_event: send a business event to the host (pass through allowlisted fields only).

Phase 1 forbids:

• Arbitrary JS execution (e.g. eval, dynamic script injection).
• Undeclared cross-origin request proxy.
• Data writes outside the allowlist.

#### 7.5.6 Suggested error codes (embed)

---

8. Non-functional requirements (extra)

• Security: keys only on the server; memory and knowledge base isolated by workspace and user; workspace member invites and code channels anti-abuse and anti-enumeration; sensitive-API logs redacted (aligned with historical decisions).
• Self-evolution safety: automatic writes must follow §3.6.2 (gates, quota, audit); forbidden to use one user’s evolution data for another user or workspace without authorization; if a skill contains executable content it must go through sandbox/approval policy.
• Performance: memory retrieve and model calls may be async; hot APIs rate-limited; evolution background jobs must limit concurrency so they do not crush storage and embedding quota.
• Operability: observability metrics, alerts, and backup for runtime and index jobs are defined in deploy docs; evolution jobs need their own metrics (success rate, latency, queue depth).
• Runtime observable events: the conversation execution path must emit traceable events (e.g. model-call start/end, tool-call start/end, retrieve-hit summary, degrade path), associated with request_id, session_id, user_agent_id, workspace_id; events may be used for admin troubleshooting and audit export.
• Skill-contract governance: skills need a minimum metadata contract (skill_id, version, input/output constraints, permission scope, timeout and retry policy, visibility), support start/stop and canary; new or upgraded skills keep a version audit record and can roll back.
• RAG policy switches: the retrieve path should support staged switches and config (vector recall, keyword recall, rerank, query rewrite); default policy prefers stability and controllable cost; switch changes must be auditable and support workspace-level override.

---

9. Version history

---

10. TODO

• [ ] §4.6 unified conversation: im_* data model, REST, and Runtime orchestration; chat → unified-conversation migration; 界面与布局.md Messages-area redesign
• [ ] Agent leasing: public-marketplace listing, agent_leases and billing terms, remark names on both sides, leased-agent triggered replies in groups
• [ ] -runtime module design doc (Soul/Memory/orchestration and LLM-gateway interfaces and data model; including Workspace on-disk layout and DB version pointers, index rebuild, memory_search implementation)
• [ ] Self-evolution implementation design: skill-deposit pipeline, memory promotion and Dreaming schedule, profile-update policy, §3.6.2 gate and audit table structure; admin job and review UI
• [ ] Runtime observable-event spec: event types, field dictionary, sampling and redaction; backend logs aligned with admin query APIs
• [ ] Skill contract V1: skill metadata, input/output constraints, permission model, timeout/retry, version rollback and publish flow
• [ ] RAG policy config center: configurable switches for vector recall/keyword recall/rerank/query rewrite and workspace-level override
• [ ] Standards library (§3.2.2): ~~storage, publish flow, plugin read-only, conversation injection, multi-dimension index trees and full-screen admin UI (shipped 2026-07-25)~~; ~~agent writes standards-library article drafts (2026-08-07)~~; pending: source allowlist and crawl, subscribe and impact lists, cross-plugin signed-call audit; mechanism: docs/core-mechanisms/规范库.md
• [ ] Asset library (§3.2.3): ~~metadata and files, upload/publish/retire, full-screen admin, plugin read-only, conversation metadata (shipped 2026-07-25)~~; ~~members upload and publish office styles, conversation pick (2026-08-15)~~; pending: index-tree browse, hard quota gate, import from skills/plugins, auto-fill toolchain; as practice-checklist raw material; mechanism: docs/core-mechanisms/资料库.md
• [x] Check schemes (§3.2.4): storage, publish gate (cited standard required), admin page, plugin read-only, agent writes drafts, questionnaire source change, stock migrate-in, admin import/export shipped; pending: Q&A injection boundary strengthening; mechanism: docs/core-mechanisms/检查方案.md
• [x] Compliance practice checklist → machine pack (§4.2.4): ~~skill distribution and prompt to install into Skills center when opening Compliance~~; ~~product decision: write into check schemes~~; ~~platform check-scheme capability + questionnaire source change + stock migrate-in~~; pending: compliance-side independent validate/preview enhancement; detail 合规实践检查表转机读包.md
• [ ] Admin-console spec: 管理员端规格.md already revised to runtime/LLM ops (v0.3); when landing, check API paths and metrics
• [ ] Web / Mobile: full sign-in and chat REST path (including attachments)
• [ ] Agent marketplace and train, memory-index job integration
• [ ] Paid and subscription entitlement check
• [ ] Unit tests and integration tests
• [ ] Phase 2: streaming output, OpenAPI 3.x, stronger security headers and CSP

---

11. References

• OpenClaw concept reference (implementation-paradigm cross-check, not a runtime dependency): Memory Overview, Dreaming, Gateway Architecture, Agent Loop, SOUL.md Guide
• Hermes Agent (concept cross-check: learning loop and skill deposit, not a runtime dependency): NousResearch/hermes-agent
• Web through backend (decision truth): docs/后端与Web设计.md
• My-agent embed SDK integration contract: sdk/host-embed/SDK契约.md
• Third-party embed-assistant guide (overview): sdk/host-embed/README.md
• Website-embed integration notes (deliverable to the host): sdk/host-embed/网站集成说明.md
• Host knowledge-document writing: sdk/host-embed/宿主知识文档撰写要求.md
• Business-integration samples (host enhance / platform plugin): plugins/hr/ (official HR), plugins/email/ (official email), plugins/camera/ (official camera), examples/hr-multi-tenant/, examples/henry-iway-compliance/ (latter truth: docs/PRODUCT.md, Next.js skeleton: examples/henry-iway-compliance/web/)
• Standards library (laws and management standards): docs/core-mechanisms/规范库.md (pairs with §3.2.2)
• Check schemes (practice machine packs): docs/core-mechanisms/检查方案.md (pairs with §3.2.4)
• Practice checklist → machine pack: docs/core-mechanisms/合规实践检查表转机读包.md (pairs with §3.2.2 / §3.2.3 / §3.2.4 / §4.2.4)
• Asset library (templates and tables): docs/core-mechanisms/资料库.md (pairs with §3.2.3)
• Asset library (templates and tables): docs/core-mechanisms/资料库.md (pairs with §3.2.3)
• Admin-console functional spec: docs/管理员端规格.md
• SMS verification code (Lianlu template send, signature, Go sample): docs/手机验证码发送集成说明.md (pairs with DESIGN decision 35)
• React: https://react.dev
• Tailwind CSS: https://tailwindcss.com
• axios: https://axios-http.com

---

*End of this document.*