When the user runs into a problem or wants to suggest an improvement, you (the agent) write the full feedback on the spot — you are there on the scene, so reproduction steps, the original error text, and actual vs. expected are three things you naturally have, and they are exactly what the user finds hardest to provide.
When to act
- The user complains naturally(“Why did it fail again”, “this is so annoying”, “this isn’t right”, “can this be changed”) → offer to note down a feedback entry: one sentence, without interrupting what they are doing and without requiring the user to learn any command first. Example: “I can write this issue up as feedback and submit it to the maintainer right now, want me to?”
- Offercan be ignored: if the user does not respond, continue the original task; for the same issue within the same session,do not bring it up againa second time (even if the same error appears again, do not bring it up).
- The user names it directly(“give the author some feedback”, “report a bug”) → go straight into the process; there is no need to first create a failure.
- 🔴 Never send automatically. Sending always happens only after the user has seen the full text and explicitly agreed.
Process
1. Classify and write it up
First determine whether it is bug(did something and did not get the expected result) / friction(the result was right but the process was awkward) / idea
(want it to do more) — one of these three categories — thenread references/report-protocol.md, and write it up by self-checking against that category branch’s questions
(the three branches do not ask the same set of things; the report skeleton is fixed, and within sections you write freely). After writing, perform the authenticity interception per the protocol:
every detail must correspond to a tool call that actually happened in this session, and anything that does not match must be deleted or marked “unverified”; keep observations and inferences separate;
the body may draw only on three kinds of material (actions in this session / errors and returns / whitelisted machine facts), and must never quote the user’s body text or materials.
Save the report as a temporary markdown file (e.g. feedback-report.md）。
2. Assemble the payload (machine facts are collected by the script according to the whitelist)
python3 scripts/submit_feedback.py prepare --category bug \
--report feedback-report.md --out feedback-payload.json \
--agent claude-code --command "1:node reconcile.mjs --dry-run"
--command are the ones executed in this sessionthis repocommands and exit codes (format “exit code:command”, may appear multiple times).
Machine facts are collected only from the whitelist: each package’s .dby/origin.json slug/version/hash/ref/installedAt, scope root lock,
Node version, operating system, agent type, and the above commands.Anything outside the whitelist is never collected— never collect
DOUBAOYA_API_KEY or any credentials, appid, author, publicAccountName, targetAccount, ipProfile,
the user’s article body text, account charter, or creative DNA. Do not read configuration files yourself to “supplement environment information”; collection goes only through the script.
The script runs credential and high-entropy detection on all content to be sent (including the body text you wrote):if it hits, do not send, and after handling it at the location it indicates, run prepare again.
3. The user reviews the full text
Present the prepare printed byfull text verbatimPresent it to the user—this is the copy that is about to be sent (identical byte-for-byte to the --out file),
not a summary and not a rewrite. After presenting it, ask explicitly, "Confirm submission?"
4. Send only after explicit consent
- The user explicitly says to send →
python3 scripts/submit_feedback.py send --payload feedback-payload.json --user-consented - The user declines or does not respond → do not send. If you want to keep a copy,
keep --payload feedback-payload.json(local only, zero requests); if you do not want to keep a copy, delete the payload and the report file.--user-consentedmay be transmitted only after the user explicitly consents.
5. Report the outcome
- Success: tell the user it has been submitted and provide the returned requestId (it can be referenced in follow-up questions). If the response contains a
noticefield, relay it verbatim. - Endpoint unreachable / not configured / returns failure: the script will write the feedback as a local markdown file (exit code 2). Tell the user theabsolute path it prints and the manual delivery methodverbatim—the feedback has been written and will not be lost just because the endpoint is unreachable.
Installation identifier (how to describe it to the user)
Send onelocally randomly generated installation identifierwith the feedback: it contains no identity information about the user (it is not derived from the machine name/username/email/key),
and the user can reset it at any time with python3 scripts/submit_feedback.py reset-id . When the user asks, say exactly this,
do not use the word "anonymous"—for the wording red lines, see references/maintainer-loop.md(the maintainer-side consumption path is also there).
What to do if something goes wrong
- There is no python3 on this machine → the report markdown has already been written; give it directly to the user to keep, and tell them the manual delivery method (open an issue in the GitHub repository zizhanovo/doubaoya-community and paste in the content).
- The endpoint has been unreachable for a long time → a local file will be written every time; truthfully tell the user that for now it can only be delivered manually, and do not repeatedly retry and rack up failures.
- The user changes their mind midway → stop immediately; keep or delete the already-generated local files according to the user's wishes.