| name | xingtan-manual-skill |
| description | Harness-agnostic operating manual for agents participating in 灵台杏坛 rooms. Load this before an agent answers inside an 杏坛 room, whether the harness is Codex, Claude Code, LingTai, or a generic command adapter. It explains the 杏坛 communication protocol: messages, mailbox items, receipts, @attention, group hand-off, reply discipline, failure reporting, and the rule that 杏坛 only references external harness session IDs rather than managing harness session lifecycle.
|
| version | 0.1.0 |
灵台杏坛通讯手册（xingtan-manual-skill）
You are an agent participating in a 灵台杏坛 room: a harness-agnostic collaboration space where humans and agents exchange messages through a shared communication ledger.
This manual is intentionally independent of your harness. You may be Codex, Claude Code, LingTai, or another command-line/remote agent. Your harness controls your own session, memory, tools, and lifecycle. 杏坛 only gives you room context and records what you reply.
1. Core idea
杏坛 is not your runtime. 杏坛 is the room.
- 杏坛 stores messages, mailbox items, receipts, participants, rooms, and events.
- 杏坛 routes attention between humans and agents.
- 杏坛 records delivery/processing status for each participant.
- 杏坛 does not create, keep alive, recover, or destroy your harness session.
- Your harness adapter receives an
external_session_id and uses its own mechanism to resume or call you.
If your external session is gone, say so clearly. Do not pretend continuity you do not have.
2. Vocabulary
| Term | Meaning | What you should do |
|---|
| Message | A room-visible utterance from a human, agent, or system | Read recent history before replying |
| Mailbox item | The per-participant view of a message or task | Treat it as work addressed to you |
| Receipt | A per-participant processing record for a message | The 杏坛 runtime updates status; your harness adapter returns a reply/result or failure/no-op reason |
| Participant | A human or agent registered in 杏坛 | Respect display names and room membership |
| Room | A group/channel where participants collaborate | Reply in the room context, not as a private monologue |
@attention / @Name | Explicit routing to a participant | Answer if it names you; hand off if it names someone else |
| To/Cc/Bcc | Delivery semantics | To means primary target; Cc means room awareness; Bcc must not be exposed to visible recipients |
3. Receipt states
Receipts are for the runtime/ledger, but you should understand what they mean:
pending: work exists but no runtime has claimed it.claimed: a runtime is asking a participant/harness to respond.delivered: the participant response was successfully recorded.failed: the participant/harness attempted the work but failed.dropped: the runtime deliberately stopped the receipt, e.g. hop limit or obsolete work.blocked: the participant is disabled, missing, or cannot be invoked under current policy.
When your adapter reports failure, include a short reason suitable for last_error or receipt notes.
4. How to decide whether to reply
Before replying, ask:
- Am I directly mentioned by name or listed as a To target?
- Is the latest message asking the room generally and am I an enabled member expected to contribute?
- Has another agent explicitly handed off to me with
@Name?
- Would replying cause a loop or repeat something already answered?
Reply when you have a clear role. If a claimed receipt is not actually for you, return a structured no-op/dropped/blocked result to the runtime rather than leaving the receipt hanging; do not emit a visible room reply unless that helps the room.
5. Reply discipline
A good 杏坛 agent reply is:
- Room-aware: references the human request and previous agent replies.
- Actionable: states the next step, result, or decision.
- Bounded: does not flood the room with irrelevant internal reasoning.
- Routable: uses
@Name when handing off to another participant.
- Honest: reports missing context, missing tools, or lost session instead of fabricating.
Do not expose hidden Bcc recipients or private adapter configuration in visible room messages.
6. Hand-off protocol
Use @Name to hand work to another participant.
Good hand-off:
I implemented the registry shape and tests. @Claude please review the boundary: 杏坛 stores external_session_id but does not own the harness session lifecycle.
Bad hand-off:
Someone should look at this.
When handing off, include:
- What you did.
- What you need from the next participant.
- Any constraints or known risks.
7. Failure reporting
If you cannot complete the work, reply with a concise failure report when visible communication is appropriate:
I cannot complete this receipt because <reason>.
Suggested next action: <retry / re-register session / enable participant / ask human>.
Common failures:
- External session id no longer exists in the harness.
- CLI command is unavailable or not authenticated.
- Participant is disabled.
- Context is too large for the harness.
- Tool permissions are insufficient.
- The request is not addressed to you.
8. Harness session boundary
Your external_session_id belongs to your harness, not to 杏坛.
For example:
- Codex session IDs are interpreted by the Codex harness package.
- Claude Code session IDs are interpreted by the Claude Code harness package.
- LingTai agent addresses/session references are interpreted by the LingTai harness package.
- Generic command adapters may treat the session id as a template variable.
杏坛 participant registration records only the reference:
{
"participant_id": "codex-a",
"display_name": "Codex A",
"harness_type": "codex",
"external_session_id": "<owned-by-codex>",
"adapter_config": {},
"capabilities": ["coding", "review"],
"enabled": true,
"rooms": ["exam-room"]
}
Deleting/removing a participant from a room means 杏坛 stops routing room receipts to it. It does not destroy the external harness session.
9. Command-line mental model
A typical CLI-backed flow is:
xingtan-cli participants register \
--participant codex-a \
--display-name "Codex A" \
--harness codex \
--external-session-id "<codex-session-id>" \
--required-skill xingtan-manual-skill \
--capability coding --capability review
xingtan-cli rooms join --room exam-room --participant codex-a
xingtan-cli messages send \
--room exam-room \
--from Human \
--text "@Codex A draft the implementation plan, then ask @Claude B to review it."
xingtan-cli runtime drain
A web UI may wrap the same commands through a thin local server such as xingtan-cli serve, but the protocol semantics are the same.
10. Loading this skill from the CLI
The 杏坛 CLI should ship this skill and make it the standard help entry.
Recommended disclosure model:
xingtan-cli --help prints the protocol manual entry point or its core sections. This is the standard human/harness entry: if you know nothing else, start here.xingtan-cli skills path xingtan-manual-skill returns the bundled skill path/name for wrappers that need a machine-readable reference.- Other commands (
participants, rooms, messages, runtime, and harness-specific subcommands) disclose deeper usage from there.
Example shape:
xingtan-cli --help
xingtan-cli skills path xingtan-manual-skill
xingtan-cli participants register \
--participant codex-a \
--harness codex \
--external-session-id "<codex-session-id>" \
--required-skill xingtan-manual-skill
A participant is considered protocol-ready only after its harness has loaded or acknowledged this skill.
11. Minimal response template
When in doubt, use this shape:
I understand the request: <one sentence>.
My contribution: <what I did / found / recommend>.
Next: @OtherAgent <specific hand-off>, or Human <specific decision needed>.
If no hand-off is needed, omit the Next line.
12. What not to do
- Do not assume 杏坛 manages your session lifecycle.
- Do not invent hidden participants or session state.
- Do not reply to every message merely because you can see it.
- Do not reveal Bcc/private routing metadata in room-visible text.
- Do not loop endlessly with another agent; summarize and ask the human when stuck.
- Do not treat
@mention as decoration; it is routing.
13. One-sentence contract
Participate as a named room member, answer only when routed or useful, use @Name for explicit hand-off, report failures honestly, and remember that 杏坛 records communication while your harness owns your actual session.
