92 lines
3.2 KiB
Markdown
92 lines
3.2 KiB
Markdown
# 1C Agent Coding Contract
|
||
|
||
This contract is the default rule set for coding agents that work through the
|
||
1C adapter.
|
||
|
||
## Default View
|
||
|
||
- Read current code and metadata from the working saved-state layer by default.
|
||
- For REST calls, use `state=working`.
|
||
- For MCP calls, use `source_state=working`.
|
||
- Treat saved-state objects as current programming state even when they are not
|
||
activated yet.
|
||
- Objects can exist only in saved-state and can later be activated or canceled.
|
||
Do not hide them from the agent view.
|
||
|
||
## Compare Views
|
||
|
||
- Use `state=both` or `source_state=all` only when the task needs a comparison
|
||
with activated runtime state.
|
||
- Show the effective working text first.
|
||
- Mark comparison details explicitly:
|
||
- `saved_state`: saved and not activated;
|
||
- `active`: activated runtime state;
|
||
- `text_source`: which layer produced the returned text;
|
||
- `comparison.differs`: whether both layers exist and differ.
|
||
|
||
## Read Workflow
|
||
|
||
Use public names and selectors:
|
||
|
||
1. `extension.objects.find` with `state=working` to find extension objects.
|
||
2. `code.search` with `state=working` to find routines or fragments.
|
||
3. `code.read` with `state=working` to read the module or routine.
|
||
4. `code.read` with `state=both` only for an explicit saved-vs-active check.
|
||
|
||
Agents should ask for and report object names, routine names, and code text.
|
||
They should not ask users for SQL tables, storage file names, stream indexes, or
|
||
saved-state write flags during normal coding work.
|
||
|
||
## Write Workflow
|
||
|
||
All normal BSL writes go through `code.write`.
|
||
|
||
Supported public edit shapes:
|
||
|
||
- replace a whole module with `module_text`, `full_text`, or `code`;
|
||
- replace one procedure or function with `routine_name` and `routine_text`;
|
||
- replace one unique fragment with `old` and `new`; when `routine_name` is
|
||
supplied, the adapter scopes the replacement to that routine.
|
||
|
||
`code.write` saves into saved-state automatically. A coding agent should simply
|
||
say "save this code" and send the desired code text. It must not ask whether SQL
|
||
saved-state apply flags are allowed.
|
||
|
||
Every successful `code.write` response must show:
|
||
|
||
- `write_mode.target=saved_state`;
|
||
- `write_mode.activation_state=not_activated`;
|
||
- `write_mode.production_apply=false`.
|
||
|
||
## Hidden Storage Details
|
||
|
||
The form module container marker `///----` is adapter-owned storage syntax.
|
||
Public `code.read` and `code.search` responses must not expose it as BSL.
|
||
Full-module writes must preserve the marker internally when the saved form
|
||
payload requires it.
|
||
|
||
Low-level methods such as `metadata.module.write_apply`, `metadata.write`, SQL
|
||
tables, stream refs, and saved-state apply flags are diagnostic tools. They are
|
||
not the default programming interface for agents.
|
||
|
||
## Agent Response Shape
|
||
|
||
When reporting a working saved-state result to a user, prefer concise wording:
|
||
|
||
```text
|
||
В working/save вижу формы:
|
||
t_Форма
|
||
tt_Форма3
|
||
ФормаЭлемента
|
||
|
||
Код читается из saved_state, еще не активирован.
|
||
```
|
||
|
||
If the user asks to compare active and saved state:
|
||
|
||
```text
|
||
Working/save: найдено, источник saved_state, не активировано.
|
||
Active: не найдено.
|
||
Эффективный код для программирования сейчас берется из saved_state.
|
||
```
|